@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
@@ -1,4 +1,8 @@
1
- import type { TreeSource } from "../render/request.js";
1
+ import { type AudienceOverlay } from "../audience/compose.js";
2
+ import { type AudienceOverlayReader } from "../audience/overlay-store.js";
3
+ import type { TreeId } from "../ids.js";
4
+ import { type Result } from "../result.js";
5
+ import type { TreeSource, TreeSourceError } from "../render/request.js";
2
6
  import type { TreeReader } from "./store.js";
3
7
  /**
4
8
  * The adapter that lets the renderer read from the store.
@@ -20,4 +24,56 @@ import type { TreeReader } from "./store.js";
20
24
  * this passes the snapshot through the same boundary any other source would.
21
25
  */
22
26
  export declare const treeSourceFromStore: (store: TreeReader) => TreeSource;
27
+ /**
28
+ * Where a deployment's audience rules and audience-scoped deltas come from.
29
+ *
30
+ * A seam rather than a table, and deliberately: 0263's store dimension is a
31
+ * schema change on top of 0260's, and the composition above it needs none of
32
+ * that to be built or tested. A deployment holding its forms in a module
33
+ * satisfies this; so will the store, once the dimension lands.
34
+ *
35
+ * Keyed by tree because that is what a request names, and answered whole
36
+ * because both halves are cacheable beside the base (0263 clause 3).
37
+ */
38
+ export interface AudienceOverlaySource {
39
+ readonly load: (treeId: TreeId) => Promise<Result<AudienceOverlay, TreeSourceError>>;
40
+ }
41
+ /**
42
+ * The composing sibling of `treeSourceFromStore` — one tree per id stays the
43
+ * right answer for a deployment that wants it, so this is a second function
44
+ * rather than an option on the first (0263).
45
+ *
46
+ * Two reads and a pure composition: the base from the store, the overlay from
47
+ * wherever a deployment keeps it, and `composeTreeForContext` over the
48
+ * request's own context. Nothing about the reader leaves the process (0262).
49
+ *
50
+ * **A composition that cannot be served reads as `unavailable`**, with the
51
+ * reason in `detail`. The code is not widened to say *stale form* because
52
+ * `TreeSourceError` is published and exhaustively switched on by hosts, and
53
+ * what a caller does about it is what it does about any other page it cannot
54
+ * have — the sentence that says which audience and which revision is the part
55
+ * somebody acts on, and that is in `detail`.
56
+ */
57
+ export declare const composingTreeSourceFromStore: (store: TreeReader, overlays: AudienceOverlaySource) => TreeSource;
58
+ /**
59
+ * The store, as the composition's `AudienceOverlaySource`.
60
+ *
61
+ * The seam 0359 clause 6 declared instead of a table now has the table under
62
+ * it, and this is the one function that joins them. It is the audience
63
+ * dimension's `treeSourceFromStore`: two reads above it, a pure composition
64
+ * beside it, and nothing about the reader leaving the process (0262).
65
+ *
66
+ * **A page with no rules is an empty overlay and not a failure**, which is what
67
+ * the store answers and what `composeTreeForContext` serves the base for. So
68
+ * wiring the composing source into a deployment that has never defined an
69
+ * audience changes nothing about what it serves — the property 0359 promised
70
+ * and the one this adapter must not quietly break.
71
+ *
72
+ * `unreadable` and `out-of-date` both read as `unavailable` here for the reason
73
+ * the composition's own errors do: `TreeSourceError` is published and
74
+ * exhaustively switched on by hosts, what a caller does about a page it cannot
75
+ * have does not change with the reason, and the sentence somebody acts on is in
76
+ * `detail`.
77
+ */
78
+ export declare const audienceOverlaySourceFromStore: (overlays: AudienceOverlayReader) => AudienceOverlaySource;
23
79
  //# sourceMappingURL=source.d.ts.map
@@ -1,4 +1,6 @@
1
- import { ok } from "../result.js";
1
+ import { composeTreeForContext, describeComposeError, } from "../audience/compose.js";
2
+ import { describeAudienceOverlayError, } from "../audience/overlay-store.js";
3
+ import { err, ok } from "../result.js";
2
4
  import { describeStoreError } from "./errors.js";
3
5
  /**
4
6
  * The adapter that lets the renderer read from the store.
@@ -34,4 +36,66 @@ export const treeSourceFromStore = (store) => ({
34
36
  return ok(head.value);
35
37
  },
36
38
  });
39
+ /**
40
+ * The composing sibling of `treeSourceFromStore` — one tree per id stays the
41
+ * right answer for a deployment that wants it, so this is a second function
42
+ * rather than an option on the first (0263).
43
+ *
44
+ * Two reads and a pure composition: the base from the store, the overlay from
45
+ * wherever a deployment keeps it, and `composeTreeForContext` over the
46
+ * request's own context. Nothing about the reader leaves the process (0262).
47
+ *
48
+ * **A composition that cannot be served reads as `unavailable`**, with the
49
+ * reason in `detail`. The code is not widened to say *stale form* because
50
+ * `TreeSourceError` is published and exhaustively switched on by hosts, and
51
+ * what a caller does about it is what it does about any other page it cannot
52
+ * have — the sentence that says which audience and which revision is the part
53
+ * somebody acts on, and that is in `detail`.
54
+ */
55
+ export const composingTreeSourceFromStore = (store, overlays) => ({
56
+ load: async (request) => {
57
+ const base = await store.head(request.treeId);
58
+ if (!base.ok) {
59
+ return err({
60
+ code: base.error.code === "not-found" ? "not-found" : "unavailable",
61
+ detail: describeStoreError(base.error),
62
+ });
63
+ }
64
+ const overlay = await overlays.load(request.treeId);
65
+ if (!overlay.ok)
66
+ return overlay;
67
+ const composed = composeTreeForContext(base.value, overlay.value, request.context);
68
+ return composed.ok
69
+ ? ok(composed.value.tree)
70
+ : err({ code: "unavailable", detail: describeComposeError(composed.error) });
71
+ },
72
+ });
73
+ /**
74
+ * The store, as the composition's `AudienceOverlaySource`.
75
+ *
76
+ * The seam 0359 clause 6 declared instead of a table now has the table under
77
+ * it, and this is the one function that joins them. It is the audience
78
+ * dimension's `treeSourceFromStore`: two reads above it, a pure composition
79
+ * beside it, and nothing about the reader leaving the process (0262).
80
+ *
81
+ * **A page with no rules is an empty overlay and not a failure**, which is what
82
+ * the store answers and what `composeTreeForContext` serves the base for. So
83
+ * wiring the composing source into a deployment that has never defined an
84
+ * audience changes nothing about what it serves — the property 0359 promised
85
+ * and the one this adapter must not quietly break.
86
+ *
87
+ * `unreadable` and `out-of-date` both read as `unavailable` here for the reason
88
+ * the composition's own errors do: `TreeSourceError` is published and
89
+ * exhaustively switched on by hosts, what a caller does about a page it cannot
90
+ * have does not change with the reason, and the sentence somebody acts on is in
91
+ * `detail`.
92
+ */
93
+ export const audienceOverlaySourceFromStore = (overlays) => ({
94
+ load: async (treeId) => {
95
+ const overlay = await overlays.overlay(treeId);
96
+ return overlay.ok
97
+ ? overlay
98
+ : err({ code: "unavailable", detail: describeAudienceOverlayError(overlay.error) });
99
+ },
100
+ });
37
101
  //# sourceMappingURL=source.js.map
@@ -22,7 +22,7 @@ import { type SubmissionResolution } from "./resolution.js";
22
22
  export type ResolveSubmissionsOptions = {
23
23
  readonly registry: EndpointRegistry;
24
24
  /** Passed through to every endpoint — the render request's host context. */
25
- readonly context?: JsonObject;
25
+ readonly context?: JsonObject | undefined;
26
26
  /**
27
27
  * How long any one endpoint is given, each independently of the others.
28
28
  * Defaults to `DEFAULT_ENDPOINT_CEILING_MS`; there is no way to wait forever
@@ -13,4 +13,5 @@ export * from "./memory.js";
13
13
  export * from "./remeasure.js";
14
14
  export * from "./retention.js";
15
15
  export * from "./sink.js";
16
+ export * from "./window.js";
16
17
  //# sourceMappingURL=index.d.ts.map
@@ -13,4 +13,5 @@ export * from "./memory.js";
13
13
  export * from "./remeasure.js";
14
14
  export * from "./retention.js";
15
15
  export * from "./sink.js";
16
+ export * from "./window.js";
16
17
  //# sourceMappingURL=index.js.map
@@ -2,6 +2,7 @@ import type { ProposalId, TreeId } from "../ids.js";
2
2
  import { type PageDirection, type PageEnds } from "../paging.js";
3
3
  import type { Result } from "../result.js";
4
4
  import type { AssessmentSummary, TelemetryRecord } from "./event.js";
5
+ import type { TelemetrySpan, TelemetryWindow } from "./window.js";
5
6
  /**
6
7
  * Where the narrated runtime goes to be read later.
7
8
  *
@@ -57,6 +58,23 @@ export type TelemetryReadRequest = {
57
58
  */
58
59
  readonly direction?: PageDirection;
59
60
  readonly limit?: number;
61
+ /**
62
+ * A stretch of wall-clock time, over `recordedAt`. Absent reads the whole
63
+ * journal, which is what every read did before windows existed.
64
+ *
65
+ * A window and a cursor are not alternatives and compose: the window says
66
+ * which records the read is about and the cursor says how far through them it
67
+ * has got. Paging a window walks that window and stops at its end — the
68
+ * `beyond` probe every implementation uses to name its cursors is taken
69
+ * *inside* the bound, so a reader paging to the end of last week is told it
70
+ * has reached the end of last week rather than handed a cursor out of it.
71
+ *
72
+ * One value rather than two bounds, because the two bounds are one idea and
73
+ * were checked against each other when `telemetryWindow` built them. A
74
+ * journal cannot be handed a window that is unreadable or runs backwards,
75
+ * which is why `TelemetryError` still has nothing to say about one.
76
+ */
77
+ readonly window?: TelemetryWindow;
60
78
  };
61
79
  export type TelemetryPage = PageEnds & {
62
80
  /**
@@ -68,6 +86,20 @@ export type TelemetryPage = PageEnds & {
68
86
  * responsible for knowing which — and silently wrong when it guessed.
69
87
  */
70
88
  readonly records: readonly RecordedTelemetry[];
89
+ /**
90
+ * The stretch this page turned out to cover, and `null` when it holds nothing.
91
+ *
92
+ * Beside the cursors rather than derived from the records by each consumer,
93
+ * because the two questions a paged journal is asked are *where am I* and
94
+ * *when is this* — and only the first had an answer. A consumer taking the
95
+ * ends off the first and last record gets an empty page wrong, and cannot
96
+ * tell *no answer* from *no time covered*.
97
+ *
98
+ * It is the page's own ends, never the window's: a window is what was asked
99
+ * for and may be wider at both ends than anything that landed in it, so a
100
+ * screen naming the window would overstate what it is describing.
101
+ */
102
+ readonly span: TelemetrySpan | null;
71
103
  };
72
104
  /**
73
105
  * Larger than a tree listing's, because these are read to be folded rather than
@@ -3,6 +3,7 @@ import { ok } from "../result.js";
3
3
  import { systemClock } from "../runtime/events.js";
4
4
  import { clampTelemetryLimit, } from "./journal.js";
5
5
  import { splitLookup } from "./lookup.js";
6
+ import { telemetrySpanOf, withinTelemetryWindow } from "./window.js";
6
7
  /**
7
8
  * The telemetry journal that keeps its records in the process.
8
9
  *
@@ -44,8 +45,15 @@ export const memoryTelemetryJournal = (clock = systemClock) => {
44
45
  const limit = clampTelemetryLimit(request?.limit);
45
46
  const from = cursorPosition(request?.cursor);
46
47
  const direction = request?.direction ?? "newer";
48
+ /**
49
+ * The window is applied here, before the limit, which is what makes the
50
+ * `beyond` probe below a statement about the window rather than about the
51
+ * journal. Filtering after the slice would hand back a short page and a
52
+ * cursor pointing at a record the window excludes.
53
+ */
47
54
  const matching = records.filter((record) => (request?.treeId === undefined || record.treeId === request.treeId) &&
48
- (from === undefined || (direction === "older" ? record.seq < from : record.seq > from)));
55
+ (from === undefined || (direction === "older" ? record.seq < from : record.seq > from)) &&
56
+ withinTelemetryWindow(request?.window, record.recordedAt));
49
57
  /**
50
58
  * `older` takes the page from the far end, which is a slice rather than a
51
59
  * reverse: the records that come back are still in arrival order, because
@@ -54,6 +62,7 @@ export const memoryTelemetryJournal = (clock = systemClock) => {
54
62
  const page = direction === "older" ? matching.slice(-limit) : matching.slice(0, limit);
55
63
  return Promise.resolve(ok({
56
64
  records: page,
65
+ span: telemetrySpanOf(page),
57
66
  ...pageEnds(page.map((record) => record.seq), direction, {
58
67
  beyond: matching.length > page.length,
59
68
  resumed: from !== undefined,
@@ -1,4 +1,4 @@
1
- import { and, asc, desc, eq, gt, inArray, lt, sql } from "drizzle-orm";
1
+ import { and, asc, desc, eq, gt, gte, inArray, lt, sql } from "drizzle-orm";
2
2
  import { z } from "zod";
3
3
  import { treeIdSchema } from "../ids.js";
4
4
  import { DEFAULT_APPLICATION_ID } from "../application/application.js";
@@ -6,6 +6,7 @@ import { cursorPosition, pageEnds } from "../paging.js";
6
6
  import { err, ok } from "../result.js";
7
7
  import { assessmentSummarySchema, telemetryEventSchema } from "./event.js";
8
8
  import { clampTelemetryLimit, } from "./journal.js";
9
+ import { telemetrySpanOf } from "./window.js";
9
10
  import { splitLookup } from "./lookup.js";
10
11
  import { loomTelemetry } from "./schema.js";
11
12
  export * from "./migrate.js";
@@ -92,6 +93,7 @@ export const postgresTelemetryJournal = (db, scope = {}) => {
92
93
  const limit = clampTelemetryLimit(request?.limit);
93
94
  const from = cursorPosition(request?.cursor);
94
95
  const direction = request?.direction ?? "newer";
96
+ const window = request?.window;
95
97
  try {
96
98
  /**
97
99
  * `older` scans descending so the newest page costs one index seek rather
@@ -112,7 +114,20 @@ export const postgresTelemetryJournal = (db, scope = {}) => {
112
114
  ? undefined
113
115
  : direction === "older"
114
116
  ? lt(loomTelemetry.seq, from)
115
- : gt(loomTelemetry.seq, from)))
117
+ : gt(loomTelemetry.seq, from),
118
+ /**
119
+ * The window, as the two comparisons it is: `gte` on the inclusive
120
+ * end and `lt` on the exclusive one, so two consecutive windows
121
+ * tile. Both are on `recorded_at`, which the column index already
122
+ * orders, and both sit in the same `where` as the cursor — which is
123
+ * what keeps the `limit + 1` probe below a question about the window
124
+ * rather than about the journal.
125
+ */
126
+ window?.since === undefined
127
+ ? undefined
128
+ : gte(loomTelemetry.recordedAt, new Date(window.since)), window?.until === undefined
129
+ ? undefined
130
+ : lt(loomTelemetry.recordedAt, new Date(window.until))))
116
131
  .orderBy(direction === "older" ? desc(loomTelemetry.seq) : asc(loomTelemetry.seq))
117
132
  /** One extra row answers "is there another page" without a count. */
118
133
  .limit(limit + 1);
@@ -129,6 +144,7 @@ export const postgresTelemetryJournal = (db, scope = {}) => {
129
144
  const page = parsed.data;
130
145
  return ok({
131
146
  records: page,
147
+ span: telemetrySpanOf(page),
132
148
  ...pageEnds(page.map((record) => record.seq), direction, {
133
149
  beyond: rows.length > limit,
134
150
  resumed: from !== undefined,
@@ -0,0 +1,135 @@
1
+ import { type Result } from "../result.js";
2
+ /**
3
+ * A stretch of wall-clock time a journal can be asked for, and the stretch a
4
+ * page turned out to cover.
5
+ *
6
+ * A journal is paged by `seq`, which is arrival order and answers *the records
7
+ * before these ones*. That is not the question anybody asks out loud. "Has it
8
+ * got better since last week" is a question about time, and without a window
9
+ * the nearest thing a screen could do was fold one page against the page before
10
+ * it — two stretches of unequal wall-clock time whose inequality grows with how
11
+ * busy the deployment is, so the comparison silently changed meaning while
12
+ * every number in it stayed right.
13
+ *
14
+ * Both halves are here because they are one idea seen from two sides: the time
15
+ * a read asks for, and the time a page answered with. A consumer that can state
16
+ * the first and cannot read the second has to infer the second off the records,
17
+ * which is where it gets the empty page wrong.
18
+ */
19
+ /**
20
+ * A half-open window over `recordedAt`, in epoch milliseconds.
21
+ *
22
+ * **Over `recordedAt`, and that is not negotiable.** `recordedAt` is stamped by
23
+ * the journal on arrival; `occurredAt` is what the host said, and a host with a
24
+ * skewed serverless clock or a replayed batch is describing its own timeline. A
25
+ * bound on `occurredAt` would let a reader ask for a window and be handed
26
+ * records from outside it, in page order, with nothing saying so — the same
27
+ * argument `journal.ts` already makes about retention, that an age a writer can
28
+ * choose is an age a writer can dodge.
29
+ *
30
+ * **Epoch milliseconds rather than the ISO strings a caller held.** One instant
31
+ * may be written two ways — `2026-01-01T02:00:00Z` and
32
+ * `2026-01-01T04:00:00+02:00` — and a journal comparing those as strings orders
33
+ * them backwards and answers with a window nobody asked for. Holding the
34
+ * instants makes comparing them the only thing an implementation can do.
35
+ *
36
+ * **Half-open: `since` is included, `until` is not.** Consecutive windows tile
37
+ * without overlapping, which is the shape's whole purpose — *last week* against
38
+ * *the week before* must not count a record that landed on the boundary twice.
39
+ *
40
+ * Built only by {@link telemetryWindow}. A window assembled by hand could hold
41
+ * `NaN`, and every comparison against `NaN` is false, so one typo'd bound would
42
+ * read as *nothing happened in that week* rather than as a mistake.
43
+ */
44
+ export type TelemetryWindow = {
45
+ /** Inclusive. Absent is unbounded into the past, back to the journal's start. */
46
+ readonly since?: number;
47
+ /** Exclusive. Absent is unbounded toward the present. */
48
+ readonly until?: number;
49
+ };
50
+ /**
51
+ * The ends of the stretch a page covers, as the journal stamped them.
52
+ *
53
+ * ISO strings rather than the instants {@link TelemetryWindow} holds, because
54
+ * these are printed rather than compared: a screen saying which stretch it is
55
+ * describing wants the stamp. A caller feeding one page's end back in as the
56
+ * next read's bound hands the string to {@link telemetryWindow}, which is the
57
+ * one place a string becomes an instant.
58
+ */
59
+ export type TelemetrySpan = {
60
+ readonly from: string;
61
+ readonly to: string;
62
+ };
63
+ /**
64
+ * Why a window could not be built.
65
+ *
66
+ * Both are caller mistakes rather than states of the journal, which is why they
67
+ * are refused here and never reach it: `TelemetryError` says a journal is
68
+ * `unavailable` and nothing else, deliberately, and a typo'd bound is not a
69
+ * journal being unavailable.
70
+ */
71
+ export type TelemetryWindowFault = {
72
+ readonly code: "unreadable-bound";
73
+ readonly bound: "since" | "until";
74
+ readonly given: string;
75
+ } | {
76
+ readonly code: "inverted";
77
+ readonly since: string;
78
+ readonly until: string;
79
+ };
80
+ export declare const describeTelemetryWindowFault: (fault: TelemetryWindowFault) => string;
81
+ /**
82
+ * A window, or the reason there is not one.
83
+ *
84
+ * Takes what a caller is actually holding — an ISO string off a record's
85
+ * `recordedAt`, or a `Date` it did arithmetic on.
86
+ *
87
+ * An unbounded request, neither end named, is a window rather than a fault: it
88
+ * is what `read` does with no window at all, and a caller assembling bounds
89
+ * from two optional inputs should not have to special-case the day both are
90
+ * absent.
91
+ *
92
+ * `since` equal to `until` is allowed and is empty by construction, the window
93
+ * being half-open. That is a degenerate ask rather than a mistake, and a caller
94
+ * slicing a range into windows produces it at the edges.
95
+ */
96
+ export declare const telemetryWindow: (request: {
97
+ readonly since?: string | Date;
98
+ readonly until?: string | Date;
99
+ }) => Result<TelemetryWindow, TelemetryWindowFault>;
100
+ /**
101
+ * Whether a `recordedAt` falls inside a window — the predicate every journal
102
+ * that keeps its records in process has to apply, and the one a journal backed
103
+ * by a query expresses as a `where` instead.
104
+ *
105
+ * A `recordedAt` that cannot be read is **outside every window**, which is the
106
+ * only safe direction: a record whose stamp is unreadable cannot be claimed to
107
+ * belong to a stretch of time, and letting it in would put a record of unknown
108
+ * date inside a window somebody is about to draw a conclusion from. It stays
109
+ * visible to an unwindowed read, which is where it can be noticed.
110
+ */
111
+ export declare const withinTelemetryWindow: (window: TelemetryWindow | undefined, recordedAt: string) => boolean;
112
+ /**
113
+ * The stretch a page covers: the earliest and latest `recordedAt` among its
114
+ * records, as they were stamped.
115
+ *
116
+ * **`null` on an empty page, rather than two nulls.** A consumer taking the ends
117
+ * off the first and last record got them wrong on an empty page and had to
118
+ * remember to check — and *there is no answer* and *the answer covers no time*
119
+ * are different claims a pair of nulls cannot tell apart.
120
+ *
121
+ * **The earliest and latest rather than the first and last.** A page ascends by
122
+ * `seq`, and `seq` is allocated at insert while `recordedAt` is a clock's
123
+ * reading, so two writers whose transactions overlap can land a lower
124
+ * `recordedAt` at a higher `seq`. First-and-last would then report a span
125
+ * running backwards. A page is bounded by a clamped limit, so scanning it costs
126
+ * nothing worth saving.
127
+ *
128
+ * A stamp that cannot be read defines neither end, for the reason
129
+ * {@link withinTelemetryWindow} refuses it: it is a date nobody knows. A page
130
+ * holding nothing else spans nothing.
131
+ */
132
+ export declare const telemetrySpanOf: (records: readonly {
133
+ readonly recordedAt: string;
134
+ }[]) => TelemetrySpan | null;
135
+ //# sourceMappingURL=window.d.ts.map
@@ -0,0 +1,101 @@
1
+ import { err, ok } from "../result.js";
2
+ export const describeTelemetryWindowFault = (fault) => fault.code === "unreadable-bound"
3
+ ? `a telemetry window's ${fault.bound} is not an instant: ${JSON.stringify(fault.given)}`
4
+ : `a telemetry window ends before it begins: since ${fault.since} is after until ${fault.until}`;
5
+ const instantOf = (bound) => {
6
+ const instant = bound instanceof Date ? bound.getTime() : Date.parse(bound);
7
+ return Number.isFinite(instant) ? instant : undefined;
8
+ };
9
+ /**
10
+ * A window, or the reason there is not one.
11
+ *
12
+ * Takes what a caller is actually holding — an ISO string off a record's
13
+ * `recordedAt`, or a `Date` it did arithmetic on.
14
+ *
15
+ * An unbounded request, neither end named, is a window rather than a fault: it
16
+ * is what `read` does with no window at all, and a caller assembling bounds
17
+ * from two optional inputs should not have to special-case the day both are
18
+ * absent.
19
+ *
20
+ * `since` equal to `until` is allowed and is empty by construction, the window
21
+ * being half-open. That is a degenerate ask rather than a mistake, and a caller
22
+ * slicing a range into windows produces it at the edges.
23
+ */
24
+ export const telemetryWindow = (request) => {
25
+ const since = request.since === undefined ? undefined : instantOf(request.since);
26
+ const until = request.until === undefined ? undefined : instantOf(request.until);
27
+ if (request.since !== undefined && since === undefined)
28
+ return err({
29
+ code: "unreadable-bound",
30
+ bound: "since",
31
+ given: String(request.since),
32
+ });
33
+ if (request.until !== undefined && until === undefined)
34
+ return err({
35
+ code: "unreadable-bound",
36
+ bound: "until",
37
+ given: String(request.until),
38
+ });
39
+ if (since !== undefined && until !== undefined && since > until)
40
+ return err({
41
+ code: "inverted",
42
+ since: new Date(since).toISOString(),
43
+ until: new Date(until).toISOString(),
44
+ });
45
+ return ok({
46
+ ...(since === undefined ? {} : { since }),
47
+ ...(until === undefined ? {} : { until }),
48
+ });
49
+ };
50
+ /**
51
+ * Whether a `recordedAt` falls inside a window — the predicate every journal
52
+ * that keeps its records in process has to apply, and the one a journal backed
53
+ * by a query expresses as a `where` instead.
54
+ *
55
+ * A `recordedAt` that cannot be read is **outside every window**, which is the
56
+ * only safe direction: a record whose stamp is unreadable cannot be claimed to
57
+ * belong to a stretch of time, and letting it in would put a record of unknown
58
+ * date inside a window somebody is about to draw a conclusion from. It stays
59
+ * visible to an unwindowed read, which is where it can be noticed.
60
+ */
61
+ export const withinTelemetryWindow = (window, recordedAt) => {
62
+ if (window === undefined)
63
+ return true;
64
+ const instant = Date.parse(recordedAt);
65
+ if (!Number.isFinite(instant))
66
+ return false;
67
+ return ((window.since === undefined || instant >= window.since) &&
68
+ (window.until === undefined || instant < window.until));
69
+ };
70
+ /**
71
+ * The stretch a page covers: the earliest and latest `recordedAt` among its
72
+ * records, as they were stamped.
73
+ *
74
+ * **`null` on an empty page, rather than two nulls.** A consumer taking the ends
75
+ * off the first and last record got them wrong on an empty page and had to
76
+ * remember to check — and *there is no answer* and *the answer covers no time*
77
+ * are different claims a pair of nulls cannot tell apart.
78
+ *
79
+ * **The earliest and latest rather than the first and last.** A page ascends by
80
+ * `seq`, and `seq` is allocated at insert while `recordedAt` is a clock's
81
+ * reading, so two writers whose transactions overlap can land a lower
82
+ * `recordedAt` at a higher `seq`. First-and-last would then report a span
83
+ * running backwards. A page is bounded by a clamped limit, so scanning it costs
84
+ * nothing worth saving.
85
+ *
86
+ * A stamp that cannot be read defines neither end, for the reason
87
+ * {@link withinTelemetryWindow} refuses it: it is a date nobody knows. A page
88
+ * holding nothing else spans nothing.
89
+ */
90
+ export const telemetrySpanOf = (records) => records.reduce((span, { recordedAt }) => {
91
+ const instant = Date.parse(recordedAt);
92
+ if (!Number.isFinite(instant))
93
+ return span;
94
+ if (span === null)
95
+ return { from: recordedAt, to: recordedAt };
96
+ return {
97
+ from: Date.parse(span.from) <= instant ? span.from : recordedAt,
98
+ to: Date.parse(span.to) >= instant ? span.to : recordedAt,
99
+ };
100
+ }, null);
101
+ //# sourceMappingURL=window.js.map
@@ -0,0 +1,31 @@
1
+ import { type AudienceId } from "../audience/audience.js";
2
+ import type { AudienceOverlayStore } from "../audience/overlay-store.js";
3
+ import type { AudienceRule } from "../audience/rule.js";
4
+ import { type TreeId } from "../ids.js";
5
+ import { type TreeDelta } from "../tree/delta.js";
6
+ /**
7
+ * One suite, run against every `AudienceOverlayStore`.
8
+ *
9
+ * `memoryAudienceOverlayStore` calls itself the reference implementation; this
10
+ * is what makes that claim checkable rather than aspirational, on the terms
11
+ * `store-contract.ts`, `policy-log-contract.ts` and `project-contract.ts`
12
+ * already set. The alternative — each store asserted against its own
13
+ * expectations — is how two stores that disagree both stay green.
14
+ *
15
+ * What is checked here is what the type cannot say: that the rules are a log
16
+ * rather than a column, that their order survives a round trip, that a save
17
+ * with nothing in it does not append, that two editors racing cannot both
18
+ * commit, that a form is replaced rather than accumulated, and that a
19
+ * withdrawn form stops being served without ceasing to exist (0403).
20
+ */
21
+ export declare const CONTRACT_TREE: TreeId;
22
+ export declare const audienceNamed: (name: string) => AudienceId;
23
+ export declare const ruleFor: (audienceId: AudienceId, key: string, value: string) => AudienceRule;
24
+ /**
25
+ * A delta that is well-formed and is never applied by this suite — what is
26
+ * under test is custody, not composition, which `compose.test.ts` covers
27
+ * against the tree it belongs to.
28
+ */
29
+ export declare const formDelta: (over?: Partial<TreeDelta>) => TreeDelta;
30
+ export declare const describeAudienceOverlayStoreContract: (name: string, make: () => Promise<AudienceOverlayStore> | AudienceOverlayStore) => void;
31
+ //# sourceMappingURL=audience-overlay-contract.d.ts.map