@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
@@ -2,15 +2,31 @@ import type { AudienceId } from "../audience/audience.js";
2
2
  import type { TreeId } from "../ids.js";
3
3
  import { type PageDirection, type PageEnds } from "../paging.js";
4
4
  import type { Result } from "../result.js";
5
- import type { ReaderSignalBatch } from "./signal.js";
5
+ import type { ReaderSignalBatch, ViewKey } from "./signal.js";
6
6
  /**
7
- * Where batches wait to be rolled up.
7
+ * Where deliveries wait to be rolled up, and then where they are kept.
8
8
  *
9
- * This is a **buffer, not an archive**, and everything about it follows from
10
- * that. Aggregates are the durable artefact (0146); raw batches exist for as
11
- * long as it takes rollup to read them and no longer. A deployment that kept
12
- * them would hold the largest table in its database in order to answer
13
- * questions that are all about counters.
9
+ * It was a **buffer, not an archive**, and until 5 November everything about it
10
+ * followed from that: aggregates are the durable artefact (0146), and a raw
11
+ * batch existed for as long as it took rollup to read it and no longer. That is
12
+ * now two lifetimes rather than one
13
+ * ([0351](../../decisions/0351-a-counted-delivery-is-kept-for-a-stated-window-rather-than-deleted-by-the-fold.md),
14
+ * and the policy it serves,
15
+ * [0349](../../decisions/0349-a-projects-reader-events-are-kept-thirty-days-by-default-and-the-tallies-stay-the-durable-record.md)):
16
+ * a delivery is **counted** when it ripens and **deleted** when it is past the
17
+ * window its deployment keeps events for, thirty days by default.
18
+ *
19
+ * **The aggregates are still the durable record.** Nothing read over all time
20
+ * comes out of this table; what the kept window buys is that an operator can
21
+ * look at individual deliveries for as long as it lasts, which is what
22
+ * `docs/portal.md`'s *Events* tab is. Everything a counter answers, a counter
23
+ * goes on answering after the row is gone.
24
+ *
25
+ * So there are two positions in this table rather than one, and they move
26
+ * independently: {@link ReaderSignalJournal.counted} stamps the fold's
27
+ * instant on a prefix, and {@link ReaderSignalJournal.forget} deletes one.
28
+ * **Nothing may delete a row the fold has not stamped** — that rule lives in
29
+ * `expire.ts`, which is the only caller that deletes.
14
30
  *
15
31
  * It is deliberately the same shape as `src/telemetry/journal.ts` — append,
16
32
  * page by an opaque cursor, forget a prefix — because a second paged log that
@@ -18,7 +34,10 @@ import type { ReaderSignalBatch } from "./signal.js";
18
34
  * cursor rules to be subtly wrong. What it is not is the same *table*: a
19
35
  * journal holds what the runtime said about itself, and this holds what
20
36
  * browsers said about pages, and the two have different retention and different
21
- * volumes by two orders of magnitude.
37
+ * volumes by two orders of magnitude. The fourth operation is where the two
38
+ * shapes part company, and it is the retention rule that asked for it: a
39
+ * telemetry episode is deleted by age alone, and a delivery may not be deleted
40
+ * until it has been counted.
22
41
  */
23
42
  /**
24
43
  * The only way it fails. No `not-found` — reading a tree nothing has been
@@ -51,10 +70,57 @@ export type ReceivedBatch = ReaderSignalBatch & {
51
70
  * audiences folds into two sets of counters rather than one.
52
71
  */
53
72
  readonly audienceId: AudienceId;
73
+ /**
74
+ * When a fold counted this delivery into the counters, where one has (0351).
75
+ *
76
+ * Absent is *not yet counted*, which is what every row in the table used to
77
+ * be: before the kept window existed a counted delivery was deleted in the
78
+ * same operation, so there was no state to record. It is the only field on a
79
+ * stored row that changes after it is written, and only one writer sets it.
80
+ *
81
+ * **It is the fold's own instant, not the row's age.** `receivedAt` is what
82
+ * retention measures and this is what makes a row eligible for it — a
83
+ * delivery is deleted when it is both past the kept window and stamped here,
84
+ * never on one of the two (`expire.ts`).
85
+ */
86
+ readonly foldedAt?: string;
54
87
  };
55
88
  export type ReaderSignalReadRequest = {
56
89
  /** Absent reads every tree the handle can see, which is the scope rule (0020). */
57
90
  readonly treeId?: TreeId;
91
+ /**
92
+ * Narrow to rows the fold has counted, or to rows it has not.
93
+ *
94
+ * Absent reads both, which is what a surface listing deliveries wants and
95
+ * what every caller wanted when a counted row did not outlive its fold.
96
+ *
97
+ * **`false` is the collection scan's read and the reason this exists.** The
98
+ * scan runs from the oldest end looking for the oldest ripe delivery, and the
99
+ * oldest end of a table that keeps deliveries for thirty days is thirty days
100
+ * of rows that have already been counted. Without the filter, collection's
101
+ * cost would grow with the kept window rather than with the window it folds
102
+ * — and the kept window is the one a deployment is invited to lengthen.
103
+ */
104
+ readonly counted?: boolean;
105
+ /**
106
+ * Narrow to the deliveries of **one page view**, named by its key (0355).
107
+ *
108
+ * The one correlation the subsystem allows, and the whole of it: a caller
109
+ * hands in a key it is already holding — off a row it could already see —
110
+ * and gets that page view's deliveries. There is deliberately nothing here
111
+ * that would **enumerate** keys, and nothing that takes a row and asks *what
112
+ * else shares this one's key*, because either of those is a stitching
113
+ * primitive wearing a narrowing's clothes. One key in, one page view out.
114
+ *
115
+ * It is a filter rather than a second method so that the paging rules are the
116
+ * ones this request already has. A page view holds few deliveries, but *few*
117
+ * is a sender's choice rather than a bound, so the read that serves a drawer
118
+ * is a page like every other read here.
119
+ *
120
+ * Served by a partial index on the column, which exists because a delivery
121
+ * that names no page view is never looked up by one.
122
+ */
123
+ readonly view?: ViewKey;
58
124
  /** A cursor from a previous page's `older`/`newer`, passed back unread. */
59
125
  readonly cursor?: string;
60
126
  /** Default `newer`, which with no cursor is the oldest page — where rollup starts. */
@@ -89,7 +155,36 @@ export type ForgetOutcome = {
89
155
  readonly removed: number;
90
156
  };
91
157
  /**
92
- * Three operations, mirroring the journal's.
158
+ * What the fold is asked to stamp, as a position and the instant to write.
159
+ *
160
+ * The same prefix shape {@link ForgetBefore} takes, because it replaces that
161
+ * call in the one place a fold used to make it: counting and dropping were one
162
+ * operation and are now counting and *marking*, which is the same operation
163
+ * against a table that keeps the row (0351).
164
+ *
165
+ * The instant is the fold's, handed in rather than read from a clock here, for
166
+ * the reason every other stored timestamp in this subsystem is handed in: a run
167
+ * writes one instant across every row and every counter it touches, and a store
168
+ * that read its own clock would stamp rows a run did not think it was stamping.
169
+ */
170
+ export type CountedBefore = {
171
+ readonly before: number;
172
+ readonly at: string;
173
+ };
174
+ export type CountedOutcome = {
175
+ /**
176
+ * Rows this call stamped.
177
+ *
178
+ * Only rows that carried nothing: a row already stamped is left exactly as it
179
+ * was, so a second run over the same prefix reports nought rather than moving
180
+ * an instant that a reading has already been taken against. It is what makes
181
+ * this operation safe to repeat, which matters because the run that makes it
182
+ * is the run that has already made the counters durable.
183
+ */
184
+ readonly counted: number;
185
+ };
186
+ /**
187
+ * Four operations: the journal's three, and the stamp the kept window asked for.
93
188
  *
94
189
  * `receive` takes several batches because an ingestion endpoint may be handed
95
190
  * several and should pay for one round trip. Unlike a journal's, this batch has
@@ -100,6 +195,14 @@ export type ForgetOutcome = {
100
195
  export interface ReaderSignalJournal {
101
196
  readonly receive: (batches: readonly ReaderSignalBatch[]) => Promise<Result<void, ReaderSignalStoreError>>;
102
197
  readonly read: (request?: ReaderSignalReadRequest) => Promise<Result<ReaderSignalPage, ReaderSignalStoreError>>;
198
+ /**
199
+ * Record that a fold counted every row below a position (0351).
200
+ *
201
+ * Idempotent by construction — it stamps only what carries nothing — because
202
+ * the caller has already written the counters when it gets here, so the one
203
+ * thing it must never do is make a retry worse than the failure.
204
+ */
205
+ readonly counted: (request: CountedBefore) => Promise<Result<CountedOutcome, ReaderSignalStoreError>>;
103
206
  readonly forget: (request: ForgetBefore) => Promise<Result<ForgetOutcome, ReaderSignalStoreError>>;
104
207
  }
105
208
  //# sourceMappingURL=journal.d.ts.map
@@ -0,0 +1,22 @@
1
+ /**
2
+ * The fifth contract suite both reader-signal journals are run against: **a
3
+ * counted delivery is marked rather than deleted, and the mark is what the next
4
+ * fold reads** (0351).
5
+ *
6
+ * It is here rather than beside the three in `src/testing/reader-signal-contract.ts`
7
+ * for the reason `applied-window.contract.ts` is: that directory is another
8
+ * lane's and this is reader-signal work. The finding filed with 0316 asks for
9
+ * the set to be moved together, which is one import away.
10
+ *
11
+ * **Every property here needs two implementations to be worth asserting**,
12
+ * which is what earns it a contract rather than a test beside the memory store.
13
+ * The stamp has to be idempotent, and in Postgres that is a clause in a `WHERE`
14
+ * — `folded_at IS NULL` — while in memory it is a guard in a `map`. The filter
15
+ * has to tell three states apart, and in Postgres `null` is one of them while
16
+ * in memory the field is absent. Those are exactly the differences that make
17
+ * two stores quietly disagree, and the disagreement here would be a window
18
+ * counted twice (0158).
19
+ */
20
+ import type { ReaderSignalJournal } from "./journal.js";
21
+ export declare const describeKeptDeliveryContract: (name: string, make: () => Promise<ReaderSignalJournal> | ReaderSignalJournal) => void;
22
+ //# sourceMappingURL=kept.contract.d.ts.map
@@ -0,0 +1,111 @@
1
+ /**
2
+ * The fifth contract suite both reader-signal journals are run against: **a
3
+ * counted delivery is marked rather than deleted, and the mark is what the next
4
+ * fold reads** (0351).
5
+ *
6
+ * It is here rather than beside the three in `src/testing/reader-signal-contract.ts`
7
+ * for the reason `applied-window.contract.ts` is: that directory is another
8
+ * lane's and this is reader-signal work. The finding filed with 0316 asks for
9
+ * the set to be moved together, which is one import away.
10
+ *
11
+ * **Every property here needs two implementations to be worth asserting**,
12
+ * which is what earns it a contract rather than a test beside the memory store.
13
+ * The stamp has to be idempotent, and in Postgres that is a clause in a `WHERE`
14
+ * — `folded_at IS NULL` — while in memory it is a guard in a `map`. The filter
15
+ * has to tell three states apart, and in Postgres `null` is one of them while
16
+ * in memory the field is absent. Those are exactly the differences that make
17
+ * two stores quietly disagree, and the disagreement here would be a window
18
+ * counted twice (0158).
19
+ */
20
+ import { describe, expect, it } from "vitest";
21
+ import { batchOf, nodeId, viewed } from "../testing/reader-signal-contract.js";
22
+ const AT = "2026-11-05T09:00:00.000Z";
23
+ const LATER = "2026-11-05T10:00:00.000Z";
24
+ const unwrap = (result) => {
25
+ if (!result.ok)
26
+ throw new Error(result.error.detail);
27
+ return result.value;
28
+ };
29
+ export const describeKeptDeliveryContract = (name, make) => {
30
+ describe(`${name} — a counted delivery`, () => {
31
+ /** Three deliveries, oldest first, and the position above the second. */
32
+ const three = async () => {
33
+ const journal = await make();
34
+ await journal.receive([
35
+ batchOf([viewed("a")]),
36
+ batchOf([viewed("b")]),
37
+ batchOf([viewed("c")]),
38
+ ]);
39
+ const seqs = unwrap(await journal.read()).batches.map((batch) => batch.seq);
40
+ return { journal, before: seqs[2] };
41
+ };
42
+ const names = async (journal, counted) => unwrap(await journal.read(counted === undefined ? undefined : { counted })).batches.map((batch) => batch.signals[0]?.nodeId);
43
+ it("is still there, carrying the instant the fold was taken at", async () => {
44
+ const { journal, before } = await three();
45
+ expect(unwrap(await journal.counted({ before, at: AT })).counted).toBe(2);
46
+ expect(unwrap(await journal.read()).batches.map((batch) => batch.foldedAt)).toEqual([
47
+ AT,
48
+ AT,
49
+ undefined,
50
+ ]);
51
+ });
52
+ /**
53
+ * **The case this would double-count** (0158). The run that stamps has
54
+ * already written the counters, so a retry of the stamp must not be worse
55
+ * than the failure that caused it — and the second call must not move an
56
+ * instant a reading has been taken against.
57
+ */
58
+ it("is stamped once, however many times the prefix is marked", async () => {
59
+ const { journal, before } = await three();
60
+ await journal.counted({ before, at: AT });
61
+ expect(unwrap(await journal.counted({ before, at: LATER })).counted).toBe(0);
62
+ expect(unwrap(await journal.read()).batches.map((batch) => batch.foldedAt)).toEqual([
63
+ AT,
64
+ AT,
65
+ undefined,
66
+ ]);
67
+ });
68
+ /**
69
+ * The fold's own read. It is what stops collection scanning the kept window
70
+ * to find the handful of rows it is for, and it is what stops it folding a
71
+ * window twice.
72
+ */
73
+ it("is left out of the uncounted read and in the counted one", async () => {
74
+ const { journal, before } = await three();
75
+ await journal.counted({ before, at: AT });
76
+ expect(await names(journal, false)).toEqual([nodeId("c")]);
77
+ expect(await names(journal, true)).toEqual([nodeId("a"), nodeId("b")]);
78
+ expect(await names(journal)).toEqual([nodeId("a"), nodeId("b"), nodeId("c")]);
79
+ });
80
+ it("marks nothing where nothing is below the position", async () => {
81
+ const journal = await make();
82
+ await journal.receive([batchOf([viewed("a")])]);
83
+ const [only] = unwrap(await journal.read()).batches;
84
+ expect(unwrap(await journal.counted({ before: only?.seq ?? 0, at: AT })).counted).toBe(0);
85
+ expect(await names(journal, false)).toEqual([nodeId("a")]);
86
+ });
87
+ /**
88
+ * The expiry sweep's delete, which is the ordinary `forget` against a
89
+ * prefix the fold has already stamped. The journal does not enforce the
90
+ * *counted first* rule — that is `expire.ts`' plan, which is where the rule
91
+ * can be read — so what this asserts is that the two operations compose:
92
+ * the prefix a fold marked is a prefix retention can delete.
93
+ */
94
+ it("is deleted by the ordinary prefix forget once retention reaches it", async () => {
95
+ const { journal, before } = await three();
96
+ await journal.counted({ before, at: AT });
97
+ expect(unwrap(await journal.forget({ before })).removed).toBe(2);
98
+ expect(await names(journal)).toEqual([nodeId("c")]);
99
+ expect(await names(journal, true)).toEqual([]);
100
+ });
101
+ /** A fresh delivery is uncounted, which is the state every row starts in. */
102
+ it("starts uncounted, with nothing on the field", async () => {
103
+ const journal = await make();
104
+ await journal.receive([batchOf([viewed("a")])]);
105
+ const [only] = unwrap(await journal.read()).batches;
106
+ expect(only?.foldedAt).toBeUndefined();
107
+ expect(await names(journal, true)).toEqual([]);
108
+ });
109
+ });
110
+ };
111
+ //# sourceMappingURL=kept.contract.js.map
@@ -0,0 +1,324 @@
1
+ import type { PrimitiveRole } from "../role.js";
2
+ import { type KindKey } from "./library.js";
3
+ import type { KindReachSilence } from "./library-reach.js";
4
+ import type { LibraryAgenda, LibraryAgendaRow, LibraryWork } from "./library-agenda.js";
5
+ /**
6
+ * **Whether a deployment's component fix-list moved, and which of its errands a
7
+ * release can be said to have finished.**
8
+ *
9
+ * [`library-agenda.ts`](library-agenda.ts) joins the order of readers a
10
+ * library's components miss to the order of what their silence costs and
11
+ * publishes one errand per component: rewrite it, repair its sender, both, or
12
+ * nothing
13
+ * ([0413](../../decisions/0413-the-component-to-fix-first-is-withdrawn-from-the-order-of-readers-missed-when-its-own-silence-made-the-figure.md)).
14
+ * It is read of **one** window, and a fix-list read once says what to do. It
15
+ * never says whether doing it worked.
16
+ *
17
+ * Every other reading over a deployment's library has a comparison beside it —
18
+ * reach, senders, silence, words, pace — and the fix-list is the one that does
19
+ * not, which is the reading an operator opens twice. *I repaired the accordion's
20
+ * sender last week; has it left the list?* is not answerable by eye from two
21
+ * agendas, because the thing to compare is a **word** rather than a figure and
22
+ * two of its four members mean different things in two windows.
23
+ *
24
+ * ## The one direction it is dangerous in, and it is a new one
25
+ *
26
+ * `LibraryWork` `none` is two states and says so: *neither reading asks for
27
+ * anything about this component*, and *nothing could be said about it*. One
28
+ * row, two sentences, and the agenda publishes the silences that distinguish
29
+ * them. Held against itself across two windows, that conflation becomes a
30
+ * statement about progress, in the direction that flatters the deployment:
31
+ *
32
+ * > The accordion asked to be rewritten last week. This week the rollup is
33
+ * > behind on the page it stands on, so the order of readers missed can say
34
+ * > nothing about it, so its errand is `none`.
35
+ *
36
+ * Read as a shift, that is **done**. Nothing was done. A fix-list that reports
37
+ * its own blindness as progress is 0330's defect one reading along: the figure
38
+ * is not merely wrong, it is wrong in the direction nobody checks.
39
+ *
40
+ * So the rule, and it is the whole of this file: **a shift is read only where
41
+ * the order of readers missed spoke about the component in both windows.**
42
+ * Everywhere else the shift is `unknown`, and
43
+ * {@link LibraryAgendaChangeRow.silenced} says which window could not say while
44
+ * {@link LibraryAgendaChangeRow.silence} says why, in that reading's own
45
+ * vocabulary.
46
+ *
47
+ * **It withholds the ambiguity exactly, and that is provable rather than
48
+ * hoped for.** An errand is the answer to two questions — *do readers miss it*
49
+ * and *are its senders faulted* — and a reach silence is one of the two
50
+ * unasked. `library` and `both` each require a rank, a rank requires `missed`,
51
+ * and `missed` is `null` under every reason the reach reading has for saying
52
+ * nothing; so a silent side's errand is always `none` or `collection`, the two
53
+ * that are read off an absence. The rule therefore fires on every row whose
54
+ * errand rests on a question nobody asked and on no other row, which is
55
+ * asserted in the test file rather than argued here.
56
+ *
57
+ * The case worth reading twice is the one where the withheld errand is **true**.
58
+ * A component whose only copy is unclaimed has a real sender errand and no rank
59
+ * at all: `collection` is the right word for that window, and the shift is
60
+ * still withheld, because `turned` would say the rewrite errand ended and
61
+ * nothing in either window knows whether it did.
62
+ *
63
+ * ## Why the other half of the agenda needs no silence of its own
64
+ *
65
+ * The errand is decided off three questions — was it ranked, are its senders
66
+ * faulted, and is the rank evidence — and only the first of the three can be
67
+ * withheld. `ranked` is `missed > 0`, and `missed` is `null` under every reason
68
+ * a kind's reach reading has for saying nothing. `faulted` and `spoiled` are
69
+ * read off `silent` and `indeterminate`, which are **counts of placements**: a
70
+ * census of the senders answers them whether or not a door could be scaled or a
71
+ * window folded, and `librarySendersReachOf` publishes them beside a `silence`
72
+ * that is about its share and not about them.
73
+ *
74
+ * A kind nobody stood inside has `silent: 0` and so is not faulted, which is
75
+ * the right answer rather than a withheld one: no sender defect is demonstrable
76
+ * where nothing was there to demonstrate it. That asymmetry is the reason this
77
+ * reading publishes **no silence set of its own**: there is one reading that can
78
+ * be silent about an errand, its vocabulary is already asked of a kind, and a
79
+ * member of this file's own would be a second name for one state. What is
80
+ * published beside it is the one fact that is this reading's — *which of the two
81
+ * windows* — as {@link LibraryAgendaSide}.
82
+ *
83
+ * ## A contested row is carried, and it is not a withholding
84
+ *
85
+ * 0413 withdraws a component from the order of readers missed when its own
86
+ * silent copies made the rank. **There is no rank here to withdraw**: a shift is
87
+ * a word about an errand, and a spoiled component's errand — repair its sender —
88
+ * is the correct errand on the strength of the silence itself. So
89
+ * {@link LibraryAgendaChange.contested} is a **slice** of the rows and never a
90
+ * withholding, and a component repaired between two windows reports `done`
91
+ * exactly as it should.
92
+ *
93
+ * What it is for is the sentence on the card: *this component was contested last
94
+ * week*, which is what tells an operator why its errand changed hands rather
95
+ * than finished.
96
+ *
97
+ * ## It publishes no figure of its own
98
+ *
99
+ * Every number on a row is a source agenda's own, on that agenda's own row
100
+ * (0265, 0327), and both rows are carried whole. Three things a comparison of
101
+ * two orders might have published, and did not:
102
+ *
103
+ * - **No movement in rank.** The two orders are over two windows' populations,
104
+ * so a component can rise five places because four others stopped being
105
+ * placed. A position in two differently-populated orders is not a comparison
106
+ * of anything, and subtracting the two would publish a figure whose commonest
107
+ * cause is a release.
108
+ * - **No corrected loss**, which is the figure the 16 November finding asks
109
+ * about and is still neither agenda's.
110
+ * - **No count of what the deployment collected.** `DeploymentAgenda.subject`
111
+ * is the one word about that (0326), and a second copy of it computed here is
112
+ * how two screens come to disagree about one deployment.
113
+ *
114
+ * ## A component is counted once, however many lists name it
115
+ *
116
+ * The permanent mistake available to a comparison of two joins is a row counted
117
+ * twice (0158). Both inputs publish one row per kind; a duplicate arrives only
118
+ * from a hand-built agenda, and it is deduplicated on `kindKeyOf` with the first
119
+ * appearance kept and counted in {@link LibraryAgendaChange.duplicated}. The
120
+ * published lists walk their source agendas' own orders and take each key at
121
+ * most once, so a component twice in an input is not a component twice in a
122
+ * list.
123
+ *
124
+ * Pure, linear in the two agendas, and reaches no store, clock or DOM.
125
+ */
126
+ /**
127
+ * Which of the two windows could not speak about a component.
128
+ *
129
+ * Published beside the reason rather than folded into it, because the reason is
130
+ * the reach reading's own vocabulary and the **window** is this reading's own
131
+ * fact. A card saying *the rollup is behind on a page it stands on* has to say
132
+ * which week, or it sends a deployment to wait for a window that has already
133
+ * caught up.
134
+ */
135
+ export type LibraryAgendaSide = "earlier" | "later" | "both";
136
+ export declare const LIBRARY_AGENDA_SIDES: readonly LibraryAgendaSide[];
137
+ /** One line per side, for a surface saying which window is missing. */
138
+ export declare const describeLibraryAgendaSide: (side: LibraryAgendaSide) => string;
139
+ /**
140
+ * What became of one component's errand between two windows.
141
+ *
142
+ * The axis is the **errand** and not a figure, which is what makes the set
143
+ * small and the words plain: an operator reads a fix-list to find work, and
144
+ * reads it again to find out whether the work is still there.
145
+ */
146
+ export type LibraryAgendaShift =
147
+ /**
148
+ * It asked for work in the earlier window and asks for none now.
149
+ *
150
+ * The only member that says a release finished something, and the reason the
151
+ * silence above is withheld rather than guessed: `none` is also what a window
152
+ * that cannot speak about a component publishes.
153
+ */
154
+ "done"
155
+ /** It asked for nothing in the earlier window and asks for work now. */
156
+ | "arrived"
157
+ /**
158
+ * It asks for work in both windows and it is different work.
159
+ *
160
+ * *Readers were skipping it; now its sender is broken* and its opposite are
161
+ * both this, and the two rows carry which. An errand that changed hands is
162
+ * not an errand finished, which is the distinction a single *still open*
163
+ * member would lose.
164
+ */
165
+ | "turned"
166
+ /** It asks for the same work in both windows. */
167
+ | "standing"
168
+ /** Neither window asked for anything about it, and both windows could speak. */
169
+ | "clear"
170
+ /**
171
+ * One of the two windows could not speak about it, so there is no before and
172
+ * after to read.
173
+ *
174
+ * {@link LibraryAgendaChangeRow.silence} says which reason, and the two
175
+ * windows' own errands stand on the row either way: withheld here means *this
176
+ * reading will not call it progress*, never *the agendas said nothing*.
177
+ */
178
+ | "unknown";
179
+ export declare const LIBRARY_AGENDA_SHIFTS: readonly LibraryAgendaShift[];
180
+ /** One line per member, for a surface saying what became of a component's errand. */
181
+ export declare const describeLibraryAgendaShift: (shift: LibraryAgendaShift) => string;
182
+ /** One kind of part's errand, held against itself across two windows. */
183
+ export type LibraryAgendaChangeRow = {
184
+ readonly kind: KindKey;
185
+ /**
186
+ * What part the type plays (0114), or `null`.
187
+ *
188
+ * The later window's answer, so a surface reading a row is reading today's
189
+ * library. Always a type key here, never a role.
190
+ */
191
+ readonly role: PrimitiveRole | null;
192
+ readonly shift: LibraryAgendaShift;
193
+ /** The errand the earlier window published, whatever this reading says about progress. */
194
+ readonly was: LibraryWork;
195
+ /** The errand the later window publishes. */
196
+ readonly now: LibraryWork;
197
+ /** True where either window's rank was made by the component's own silent copies (0413). */
198
+ readonly contested: boolean;
199
+ readonly spoiledWas: boolean;
200
+ readonly spoiledNow: boolean;
201
+ /**
202
+ * Why there is no before and after, in **the reach reading's own vocabulary**
203
+ * rather than a second spelling of it.
204
+ *
205
+ * Reused outright, not respelled, the way a funnel answer reuses a page's
206
+ * reach silence: the subject is a kind in both readings and the state of the
207
+ * world is the same one — the order of readers missed had nothing to say
208
+ * about this kind of part. A member of its own here would be a second name
209
+ * for one state, which is the thing this subsystem spends the most care not
210
+ * to publish.
211
+ *
212
+ * **The later window's reason where both windows have one**, because that is
213
+ * the reason a deployment still has a remedy for; {@link silenced} says which
214
+ * window, and the earlier window's own reason stands whole on
215
+ * {@link earlier}.
216
+ */
217
+ readonly silence: KindReachSilence | null;
218
+ /** Which window could not speak, or `null` where both could. */
219
+ readonly silenced: LibraryAgendaSide | null;
220
+ /** The earlier agenda's whole row, so a surface never holds two lists side by side. */
221
+ readonly earlier: LibraryAgendaRow;
222
+ /** The later agenda's whole row. */
223
+ readonly later: LibraryAgendaRow;
224
+ };
225
+ /** Where the one thing to do first stood in each window. */
226
+ export type LibraryAgendaHead = {
227
+ /** The component at the head of the earlier agenda, or `null` where it asked for nothing. */
228
+ readonly earlier: KindKey | null;
229
+ readonly later: KindKey | null;
230
+ /**
231
+ * Whether it is the same component, two `null`s included.
232
+ *
233
+ * Read off each agenda's own `first` rather than recomputed, so a surface
234
+ * saying *the top of your list has not moved in a week* is saying what those
235
+ * two screens said.
236
+ */
237
+ readonly same: boolean;
238
+ };
239
+ /** What two windows of a deployment's component fix-list say about each other. */
240
+ export type LibraryAgendaChange = {
241
+ /** Every component on both agendas, by type, in the later agenda's own row order. */
242
+ readonly rows: readonly LibraryAgendaChangeRow[];
243
+ /**
244
+ * Components that asked for work and ask for none now, in the **earlier**
245
+ * agenda's own orders — readers missed first, then readings lost — each
246
+ * component once.
247
+ *
248
+ * The earlier agenda's order because the later one no longer ranks them: a
249
+ * component with no errand is in neither of its lists.
250
+ */
251
+ readonly done: readonly LibraryAgendaChangeRow[];
252
+ /** Components that ask for work now and asked for none, in the **later** agenda's own orders. */
253
+ readonly arrived: readonly LibraryAgendaChangeRow[];
254
+ /**
255
+ * Components asking for work in both windows, in the later agenda's own
256
+ * orders.
257
+ *
258
+ * The shifts `standing` and `turned` together, because *still on the list* is
259
+ * one question and an errand that changed hands is still on the list. Which
260
+ * of the two a row is, and what it turned from, is on the row.
261
+ */
262
+ readonly outstanding: readonly LibraryAgendaChangeRow[];
263
+ /**
264
+ * Rows whose shift this reading will not call progress, carrying both
265
+ * windows' errands.
266
+ *
267
+ * A **slice** of {@link rows} and never a list beside it, so the counts in
268
+ * {@link shifts} add to the rows there are (0158), and never dropped quietly:
269
+ * a component this reading has nothing to say about is findable with the
270
+ * reason it has nothing to say (0301, 0326).
271
+ */
272
+ readonly withheld: readonly LibraryAgendaChangeRow[];
273
+ /**
274
+ * Rows where either window's rank was its own silence's doing.
275
+ *
276
+ * A slice of {@link rows}, and **not** a withholding: an errand is not a
277
+ * rank, so a contested component's shift is read like any other's. It is the
278
+ * sentence that says why an errand changed hands rather than finished.
279
+ */
280
+ readonly contested: readonly LibraryAgendaChangeRow[];
281
+ /** How many components each shift covers, over {@link rows}. */
282
+ readonly shifts: Readonly<Record<LibraryAgendaShift, number>>;
283
+ /** Where the one thing to do first stood in each window. */
284
+ readonly head: LibraryAgendaHead;
285
+ /**
286
+ * Components one agenda named and the other did not, which is nought for a
287
+ * caller that read two windows of the same deployment.
288
+ *
289
+ * Both agendas are over *the pages their caller read*, so a caller holding
290
+ * agendas of two different sets of pages gets a comparison silently of the
291
+ * intersection.
292
+ */
293
+ readonly unpaired: {
294
+ readonly earlier: number;
295
+ readonly later: number;
296
+ };
297
+ /** Rows for a component beyond the first, on either side, which were dropped (0158). */
298
+ readonly duplicated: number;
299
+ };
300
+ /**
301
+ * Hold a deployment's component fix-list against an earlier reading of it, and
302
+ * publish what became of each errand.
303
+ *
304
+ * ```ts
305
+ * const moved = libraryAgendaChangeOf(
306
+ * libraryAgendaOf(lastWeek.reach, lastWeek.senders),
307
+ * libraryAgendaOf(thisWeek.reach, thisWeek.senders)
308
+ * )
309
+ * ```
310
+ *
311
+ * The two agendas are handed in rather than derived here, on the terms every
312
+ * derived reading in this subsystem takes readings: each is separately useful
313
+ * and separately drawn, and deriving either a second time is how two screens
314
+ * come to disagree about one deployment (0330).
315
+ *
316
+ * @param earlier The agenda of the earlier window, as `libraryAgendaOf`
317
+ * answered it.
318
+ * @param later The agenda of the later window. **Both are required**, on the
319
+ * terms every input of a fix-list is required (0322, 0343): an argument a caller
320
+ * may omit is a comparison that type-checks, runs, and calls a deployment's
321
+ * whole library finished.
322
+ */
323
+ export declare const libraryAgendaChangeOf: (earlier: LibraryAgenda, later: LibraryAgenda) => LibraryAgendaChange;
324
+ //# sourceMappingURL=library-agenda-change.d.ts.map