@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.
- package/dist/audience/compose.d.ts +112 -0
- package/dist/audience/compose.js +134 -0
- package/dist/audience/memory.d.ts +14 -0
- package/dist/audience/memory.js +71 -0
- package/dist/audience/overlay-store.d.ts +343 -0
- package/dist/audience/overlay-store.js +217 -0
- package/dist/audience/rule.d.ts +121 -0
- package/dist/audience/rule.js +78 -0
- package/dist/cli/index.d.ts +3 -4
- package/dist/cli/index.js +3 -4
- package/dist/data/adapter.d.ts +9 -1
- package/dist/data/adapter.js +2 -0
- package/dist/data/resolve.d.ts +1 -1
- package/dist/interpretation/anthropic.d.ts +1 -1
- package/dist/interpretation/anthropic.js +2 -22
- package/dist/interpretation/client.d.ts +1 -1
- package/dist/interpretation/materialize.js +67 -22
- package/dist/interpretation/openai-compatible.d.ts +36 -0
- package/dist/interpretation/openai-compatible.js +79 -0
- package/dist/interpretation/status.d.ts +19 -0
- package/dist/interpretation/status.js +26 -0
- package/dist/live/index.d.ts +73 -0
- package/dist/live/index.js +73 -0
- package/dist/live/pages.d.ts +187 -0
- package/dist/live/pages.js +161 -0
- package/dist/live/pull.d.ts +147 -0
- package/dist/live/pull.js +398 -0
- package/dist/live/pulling.d.ts +79 -0
- package/dist/live/pulling.js +117 -0
- package/dist/live/window.d.ts +129 -0
- package/dist/live/window.js +132 -0
- package/dist/render/addressed.d.ts +35 -0
- package/dist/render/addressed.js +79 -0
- package/dist/render/document-theme.d.ts +70 -0
- package/dist/render/document-theme.js +139 -0
- package/dist/render/editable.d.ts +15 -1
- package/dist/render/editable.js +13 -1
- package/dist/render/expected.d.ts +98 -0
- package/dist/render/expected.js +88 -0
- package/dist/render/index.d.ts +2 -0
- package/dist/render/index.js +2 -0
- package/dist/render/render.d.ts +11 -0
- package/dist/render/render.js +192 -46
- package/dist/render/request.d.ts +8 -1
- package/dist/render/request.js +1 -0
- package/dist/runtime/auto-apply-ceiling.d.ts +54 -0
- package/dist/runtime/auto-apply-ceiling.js +66 -0
- package/dist/runtime/gate.js +69 -10
- package/dist/runtime/index.d.ts +1 -0
- package/dist/runtime/index.js +1 -0
- package/dist/runtime/nesting.d.ts +13 -1
- package/dist/runtime/nesting.js +41 -24
- package/dist/runtime/policy-change.js +8 -2
- package/dist/runtime/policy-log.d.ts +5 -5
- package/dist/runtime/policy.d.ts +8 -6
- package/dist/runtime/policy.js +5 -2
- package/dist/runtime/repointing.js +0 -0
- package/dist/sdk/definition.d.ts +65 -6
- package/dist/sdk/definition.js +44 -0
- package/dist/sdk/registry.d.ts +17 -1
- package/dist/sdk/registry.js +39 -0
- package/dist/signals/acted.contract.d.ts +21 -0
- package/dist/signals/acted.contract.js +236 -0
- package/dist/signals/acted.d.ts +359 -0
- package/dist/signals/acted.js +135 -0
- package/dist/signals/agenda.d.ts +585 -0
- package/dist/signals/agenda.js +295 -0
- package/dist/signals/arrivals.contract.d.ts +21 -0
- package/dist/signals/arrivals.contract.js +180 -0
- package/dist/signals/arrivals.d.ts +375 -0
- package/dist/signals/arrivals.js +254 -0
- package/dist/signals/broadcast.d.ts +25 -15
- package/dist/signals/broadcast.js +209 -36
- package/dist/signals/collect.d.ts +137 -43
- package/dist/signals/collect.js +103 -36
- package/dist/signals/conversion.d.ts +348 -0
- package/dist/signals/conversion.js +235 -0
- package/dist/signals/correlated.contract.d.ts +24 -0
- package/dist/signals/correlated.contract.js +94 -0
- package/dist/signals/counters.d.ts +51 -0
- package/dist/signals/counters.js +58 -0
- package/dist/signals/deployment-change.d.ts +28 -4
- package/dist/signals/deployment-change.js +57 -16
- package/dist/signals/deployment.d.ts +18 -5
- package/dist/signals/deployment.js +37 -11
- package/dist/signals/door.d.ts +34 -12
- package/dist/signals/door.js +37 -13
- package/dist/signals/expire.d.ts +192 -0
- package/dist/signals/expire.js +213 -0
- package/dist/signals/frontier.d.ts +268 -0
- package/dist/signals/frontier.js +145 -0
- package/dist/signals/funnel-hours.contract.d.ts +21 -0
- package/dist/signals/funnel-hours.contract.js +221 -0
- package/dist/signals/funnel-hours.d.ts +293 -0
- package/dist/signals/funnel-hours.js +99 -0
- package/dist/signals/funnel.d.ts +60 -0
- package/dist/signals/funnel.js +35 -20
- package/dist/signals/health.d.ts +201 -4
- package/dist/signals/health.js +214 -2
- package/dist/signals/index.d.ts +19 -0
- package/dist/signals/index.js +19 -0
- package/dist/signals/inside.d.ts +190 -0
- package/dist/signals/inside.js +263 -0
- package/dist/signals/join.d.ts +56 -0
- package/dist/signals/join.js +60 -0
- package/dist/signals/journal.d.ts +112 -9
- package/dist/signals/kept.contract.d.ts +22 -0
- package/dist/signals/kept.contract.js +111 -0
- package/dist/signals/library-agenda-change.d.ts +324 -0
- package/dist/signals/library-agenda-change.js +199 -0
- package/dist/signals/library-agenda.d.ts +258 -0
- package/dist/signals/library-agenda.js +167 -0
- package/dist/signals/library-reach-change.d.ts +10 -0
- package/dist/signals/library-reach-change.js +11 -3
- package/dist/signals/library-senders-change.d.ts +457 -0
- package/dist/signals/library-senders-change.js +367 -0
- package/dist/signals/library-senders-reach-change.d.ts +486 -0
- package/dist/signals/library-senders-reach-change.js +538 -0
- package/dist/signals/library-senders-reach.d.ts +340 -0
- package/dist/signals/library-senders-reach.js +252 -0
- package/dist/signals/library-senders.d.ts +271 -0
- package/dist/signals/library-senders.js +180 -0
- package/dist/signals/library-word-reach-change.js +2 -6
- package/dist/signals/memory.js +142 -1
- package/dist/signals/migrate.d.ts +6 -5
- package/dist/signals/migrate.js +150 -6
- package/dist/signals/notice.d.ts +88 -33
- package/dist/signals/notice.js +38 -16
- package/dist/signals/part-pace.d.ts +378 -0
- package/dist/signals/part-pace.js +333 -0
- package/dist/signals/parts.d.ts +25 -15
- package/dist/signals/parts.js +32 -73
- package/dist/signals/postgres.js +400 -26
- package/dist/signals/region.d.ts +1 -1
- package/dist/signals/retention.d.ts +43 -21
- package/dist/signals/retention.js +25 -8
- package/dist/signals/rhythm.d.ts +302 -0
- package/dist/signals/rhythm.js +262 -0
- package/dist/signals/rollup.d.ts +127 -1
- package/dist/signals/rollup.js +211 -24
- package/dist/signals/schema.d.ts +640 -3
- package/dist/signals/schema.js +239 -3
- package/dist/signals/silences.d.ts +310 -11
- package/dist/signals/silences.js +243 -0
- package/dist/signals/subtrees.d.ts +123 -0
- package/dist/signals/subtrees.js +102 -0
- package/dist/signals/tally.d.ts +125 -4
- package/dist/signals/unread.d.ts +292 -0
- package/dist/signals/unread.js +137 -0
- package/dist/signals/window-agenda.d.ts +276 -0
- package/dist/signals/window-agenda.js +83 -0
- package/dist/signals/window-funnels.d.ts +88 -0
- package/dist/signals/window-funnels.js +47 -0
- package/dist/store/cache.d.ts +101 -0
- package/dist/store/cache.js +149 -0
- package/dist/store/history.d.ts +82 -0
- package/dist/store/history.js +36 -0
- package/dist/store/index.d.ts +11 -0
- package/dist/store/index.js +11 -0
- package/dist/store/migrate.d.ts +26 -0
- package/dist/store/migrate.js +64 -0
- package/dist/store/postgres-audience.d.ts +14 -0
- package/dist/store/postgres-audience.js +272 -0
- package/dist/store/postgres.d.ts +1 -0
- package/dist/store/postgres.js +1 -0
- package/dist/store/schema.d.ts +312 -0
- package/dist/store/schema.js +77 -0
- package/dist/store/source.d.ts +57 -1
- package/dist/store/source.js +65 -1
- package/dist/submit/resolve.d.ts +1 -1
- package/dist/telemetry/index.d.ts +1 -0
- package/dist/telemetry/index.js +1 -0
- package/dist/telemetry/journal.d.ts +32 -0
- package/dist/telemetry/memory.js +10 -1
- package/dist/telemetry/postgres.js +18 -2
- package/dist/telemetry/window.d.ts +135 -0
- package/dist/telemetry/window.js +101 -0
- package/dist/testing/audience-overlay-contract.d.ts +31 -0
- package/dist/testing/audience-overlay-contract.js +354 -0
- package/dist/testing/contracts.d.ts +1 -0
- package/dist/testing/contracts.js +1 -0
- package/dist/testing/journal-contract.js +158 -5
- package/dist/theme/contrast.d.ts +19 -14
- package/dist/theme/contrast.js +181 -17
- package/dist/tree/apply.js +13 -0
- package/dist/tree/mutation.d.ts +18 -0
- package/dist/tree/mutation.js +24 -12
- package/dist/tree/navigation.d.ts +5 -0
- package/dist/tree/navigation.js +32 -10
- package/dist/tree/outline.d.ts +7 -0
- package/dist/tree/outline.js +9 -5
- package/package.json +39 -96
- package/dist/runtime/inverse-interpreter.d.ts +0 -90
- package/dist/runtime/inverse-interpreter.js +0 -56
package/dist/store/source.d.ts
CHANGED
|
@@ -1,4 +1,8 @@
|
|
|
1
|
-
import type
|
|
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
|
package/dist/store/source.js
CHANGED
|
@@ -1,4 +1,6 @@
|
|
|
1
|
-
import {
|
|
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
|
package/dist/submit/resolve.d.ts
CHANGED
|
@@ -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
|
package/dist/telemetry/index.js
CHANGED
|
@@ -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
|
package/dist/telemetry/memory.js
CHANGED
|
@@ -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
|