@jam-overture/loom 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (194) hide show
  1. package/dist/audience/compose.d.ts +112 -0
  2. package/dist/audience/compose.js +134 -0
  3. package/dist/audience/memory.d.ts +14 -0
  4. package/dist/audience/memory.js +71 -0
  5. package/dist/audience/overlay-store.d.ts +343 -0
  6. package/dist/audience/overlay-store.js +217 -0
  7. package/dist/audience/rule.d.ts +121 -0
  8. package/dist/audience/rule.js +78 -0
  9. package/dist/cli/index.d.ts +3 -4
  10. package/dist/cli/index.js +3 -4
  11. package/dist/data/adapter.d.ts +9 -1
  12. package/dist/data/adapter.js +2 -0
  13. package/dist/data/resolve.d.ts +1 -1
  14. package/dist/interpretation/anthropic.d.ts +1 -1
  15. package/dist/interpretation/anthropic.js +2 -22
  16. package/dist/interpretation/client.d.ts +1 -1
  17. package/dist/interpretation/materialize.js +67 -22
  18. package/dist/interpretation/openai-compatible.d.ts +36 -0
  19. package/dist/interpretation/openai-compatible.js +79 -0
  20. package/dist/interpretation/status.d.ts +19 -0
  21. package/dist/interpretation/status.js +26 -0
  22. package/dist/live/index.d.ts +73 -0
  23. package/dist/live/index.js +73 -0
  24. package/dist/live/pages.d.ts +187 -0
  25. package/dist/live/pages.js +161 -0
  26. package/dist/live/pull.d.ts +147 -0
  27. package/dist/live/pull.js +398 -0
  28. package/dist/live/pulling.d.ts +79 -0
  29. package/dist/live/pulling.js +117 -0
  30. package/dist/live/window.d.ts +129 -0
  31. package/dist/live/window.js +132 -0
  32. package/dist/render/addressed.d.ts +35 -0
  33. package/dist/render/addressed.js +79 -0
  34. package/dist/render/document-theme.d.ts +70 -0
  35. package/dist/render/document-theme.js +139 -0
  36. package/dist/render/editable.d.ts +15 -1
  37. package/dist/render/editable.js +13 -1
  38. package/dist/render/expected.d.ts +98 -0
  39. package/dist/render/expected.js +88 -0
  40. package/dist/render/index.d.ts +2 -0
  41. package/dist/render/index.js +2 -0
  42. package/dist/render/render.d.ts +11 -0
  43. package/dist/render/render.js +192 -46
  44. package/dist/render/request.d.ts +8 -1
  45. package/dist/render/request.js +1 -0
  46. package/dist/runtime/auto-apply-ceiling.d.ts +54 -0
  47. package/dist/runtime/auto-apply-ceiling.js +66 -0
  48. package/dist/runtime/gate.js +69 -10
  49. package/dist/runtime/index.d.ts +1 -0
  50. package/dist/runtime/index.js +1 -0
  51. package/dist/runtime/nesting.d.ts +13 -1
  52. package/dist/runtime/nesting.js +41 -24
  53. package/dist/runtime/policy-change.js +8 -2
  54. package/dist/runtime/policy-log.d.ts +5 -5
  55. package/dist/runtime/policy.d.ts +8 -6
  56. package/dist/runtime/policy.js +5 -2
  57. package/dist/runtime/repointing.js +0 -0
  58. package/dist/sdk/definition.d.ts +65 -6
  59. package/dist/sdk/definition.js +44 -0
  60. package/dist/sdk/registry.d.ts +17 -1
  61. package/dist/sdk/registry.js +39 -0
  62. package/dist/signals/acted.contract.d.ts +21 -0
  63. package/dist/signals/acted.contract.js +236 -0
  64. package/dist/signals/acted.d.ts +359 -0
  65. package/dist/signals/acted.js +135 -0
  66. package/dist/signals/agenda.d.ts +585 -0
  67. package/dist/signals/agenda.js +295 -0
  68. package/dist/signals/arrivals.contract.d.ts +21 -0
  69. package/dist/signals/arrivals.contract.js +180 -0
  70. package/dist/signals/arrivals.d.ts +375 -0
  71. package/dist/signals/arrivals.js +254 -0
  72. package/dist/signals/broadcast.d.ts +25 -15
  73. package/dist/signals/broadcast.js +209 -36
  74. package/dist/signals/collect.d.ts +137 -43
  75. package/dist/signals/collect.js +103 -36
  76. package/dist/signals/conversion.d.ts +348 -0
  77. package/dist/signals/conversion.js +235 -0
  78. package/dist/signals/correlated.contract.d.ts +24 -0
  79. package/dist/signals/correlated.contract.js +94 -0
  80. package/dist/signals/counters.d.ts +51 -0
  81. package/dist/signals/counters.js +58 -0
  82. package/dist/signals/deployment-change.d.ts +28 -4
  83. package/dist/signals/deployment-change.js +57 -16
  84. package/dist/signals/deployment.d.ts +18 -5
  85. package/dist/signals/deployment.js +37 -11
  86. package/dist/signals/door.d.ts +34 -12
  87. package/dist/signals/door.js +37 -13
  88. package/dist/signals/expire.d.ts +192 -0
  89. package/dist/signals/expire.js +213 -0
  90. package/dist/signals/frontier.d.ts +268 -0
  91. package/dist/signals/frontier.js +145 -0
  92. package/dist/signals/funnel-hours.contract.d.ts +21 -0
  93. package/dist/signals/funnel-hours.contract.js +221 -0
  94. package/dist/signals/funnel-hours.d.ts +293 -0
  95. package/dist/signals/funnel-hours.js +99 -0
  96. package/dist/signals/funnel.d.ts +60 -0
  97. package/dist/signals/funnel.js +35 -20
  98. package/dist/signals/health.d.ts +201 -4
  99. package/dist/signals/health.js +214 -2
  100. package/dist/signals/index.d.ts +19 -0
  101. package/dist/signals/index.js +19 -0
  102. package/dist/signals/inside.d.ts +190 -0
  103. package/dist/signals/inside.js +263 -0
  104. package/dist/signals/join.d.ts +56 -0
  105. package/dist/signals/join.js +60 -0
  106. package/dist/signals/journal.d.ts +112 -9
  107. package/dist/signals/kept.contract.d.ts +22 -0
  108. package/dist/signals/kept.contract.js +111 -0
  109. package/dist/signals/library-agenda-change.d.ts +324 -0
  110. package/dist/signals/library-agenda-change.js +199 -0
  111. package/dist/signals/library-agenda.d.ts +258 -0
  112. package/dist/signals/library-agenda.js +167 -0
  113. package/dist/signals/library-reach-change.d.ts +10 -0
  114. package/dist/signals/library-reach-change.js +11 -3
  115. package/dist/signals/library-senders-change.d.ts +457 -0
  116. package/dist/signals/library-senders-change.js +367 -0
  117. package/dist/signals/library-senders-reach-change.d.ts +486 -0
  118. package/dist/signals/library-senders-reach-change.js +538 -0
  119. package/dist/signals/library-senders-reach.d.ts +340 -0
  120. package/dist/signals/library-senders-reach.js +252 -0
  121. package/dist/signals/library-senders.d.ts +271 -0
  122. package/dist/signals/library-senders.js +180 -0
  123. package/dist/signals/library-word-reach-change.js +2 -6
  124. package/dist/signals/memory.js +142 -1
  125. package/dist/signals/migrate.d.ts +6 -5
  126. package/dist/signals/migrate.js +150 -6
  127. package/dist/signals/notice.d.ts +88 -33
  128. package/dist/signals/notice.js +38 -16
  129. package/dist/signals/part-pace.d.ts +378 -0
  130. package/dist/signals/part-pace.js +333 -0
  131. package/dist/signals/parts.d.ts +25 -15
  132. package/dist/signals/parts.js +32 -73
  133. package/dist/signals/postgres.js +400 -26
  134. package/dist/signals/region.d.ts +1 -1
  135. package/dist/signals/retention.d.ts +43 -21
  136. package/dist/signals/retention.js +25 -8
  137. package/dist/signals/rhythm.d.ts +302 -0
  138. package/dist/signals/rhythm.js +262 -0
  139. package/dist/signals/rollup.d.ts +127 -1
  140. package/dist/signals/rollup.js +211 -24
  141. package/dist/signals/schema.d.ts +640 -3
  142. package/dist/signals/schema.js +239 -3
  143. package/dist/signals/silences.d.ts +310 -11
  144. package/dist/signals/silences.js +243 -0
  145. package/dist/signals/subtrees.d.ts +123 -0
  146. package/dist/signals/subtrees.js +102 -0
  147. package/dist/signals/tally.d.ts +125 -4
  148. package/dist/signals/unread.d.ts +292 -0
  149. package/dist/signals/unread.js +137 -0
  150. package/dist/signals/window-agenda.d.ts +276 -0
  151. package/dist/signals/window-agenda.js +83 -0
  152. package/dist/signals/window-funnels.d.ts +88 -0
  153. package/dist/signals/window-funnels.js +47 -0
  154. package/dist/store/cache.d.ts +101 -0
  155. package/dist/store/cache.js +149 -0
  156. package/dist/store/history.d.ts +82 -0
  157. package/dist/store/history.js +36 -0
  158. package/dist/store/index.d.ts +11 -0
  159. package/dist/store/index.js +11 -0
  160. package/dist/store/migrate.d.ts +26 -0
  161. package/dist/store/migrate.js +64 -0
  162. package/dist/store/postgres-audience.d.ts +14 -0
  163. package/dist/store/postgres-audience.js +272 -0
  164. package/dist/store/postgres.d.ts +1 -0
  165. package/dist/store/postgres.js +1 -0
  166. package/dist/store/schema.d.ts +312 -0
  167. package/dist/store/schema.js +77 -0
  168. package/dist/store/source.d.ts +57 -1
  169. package/dist/store/source.js +65 -1
  170. package/dist/submit/resolve.d.ts +1 -1
  171. package/dist/telemetry/index.d.ts +1 -0
  172. package/dist/telemetry/index.js +1 -0
  173. package/dist/telemetry/journal.d.ts +32 -0
  174. package/dist/telemetry/memory.js +10 -1
  175. package/dist/telemetry/postgres.js +18 -2
  176. package/dist/telemetry/window.d.ts +135 -0
  177. package/dist/telemetry/window.js +101 -0
  178. package/dist/testing/audience-overlay-contract.d.ts +31 -0
  179. package/dist/testing/audience-overlay-contract.js +354 -0
  180. package/dist/testing/contracts.d.ts +1 -0
  181. package/dist/testing/contracts.js +1 -0
  182. package/dist/testing/journal-contract.js +158 -5
  183. package/dist/theme/contrast.d.ts +19 -14
  184. package/dist/theme/contrast.js +181 -17
  185. package/dist/tree/apply.js +13 -0
  186. package/dist/tree/mutation.d.ts +18 -0
  187. package/dist/tree/mutation.js +24 -12
  188. package/dist/tree/navigation.d.ts +5 -0
  189. package/dist/tree/navigation.js +32 -10
  190. package/dist/tree/outline.d.ts +7 -0
  191. package/dist/tree/outline.js +9 -5
  192. package/package.json +39 -96
  193. package/dist/runtime/inverse-interpreter.d.ts +0 -90
  194. package/dist/runtime/inverse-interpreter.js +0 -56
@@ -0,0 +1,112 @@
1
+ /**
2
+ * A page as the reader in front of it gets it: the base tree, plus the deltas
3
+ * the audiences they are in have earned.
4
+ *
5
+ * This is
6
+ * [0263](../../decisions/0263-a-page-is-a-base-tree-and-the-deltas-an-audience-earns.md)
7
+ * clause 4 — *base plus matched deltas, locally, with no call to the control
8
+ * plane* — and it is a **pure function of a tree, a set of rules and a
9
+ * context**, which is what lets it run on every request in the customer's own
10
+ * process beside the render it feeds.
11
+ *
12
+ * **What comes out is a projection of a revision and not a revision of its
13
+ * own.** The composed tree keeps the base's `treeId` and the base's `revision`,
14
+ * and nothing about it is appended anywhere. Three reasons, and the third is
15
+ * the one that decided it:
16
+ *
17
+ * - A revision is a thing the log can replay and attribute. A composition is
18
+ * derived from one, per request, from rules that may change between two
19
+ * requests; it has no author, no timestamp and no place in the history.
20
+ * - Bumping the number would make a reader's revision depend on which audience
21
+ * they fell into, so two readers of the same published page would report
22
+ * different revisions for it.
23
+ * - **The measurement joins on it.** 0284 made a counter's identity
24
+ * `(application, audience, tree, revision)`. If a composition carried its own
25
+ * revision, the audience dimension and the revision dimension would move
26
+ * together and *compare these two audiences on this revision* — the whole
27
+ * point of serving two — would have nothing to compare.
28
+ *
29
+ * So the base revision is what a signal names, and the audience is what tells
30
+ * two forms of it apart. That is the shape 0284 already built the tables for.
31
+ */
32
+ import type { JsonObject } from "../json.js";
33
+ import { type Result } from "../result.js";
34
+ import type { TreeDelta } from "../tree/delta.js";
35
+ import type { LoomTree } from "../tree/tree.js";
36
+ import type { AudienceId } from "./audience.js";
37
+ import { type AudienceRule } from "./rule.js";
38
+ /** The delta one audience earns, against the base it was authored on. */
39
+ export type AudienceForm = {
40
+ readonly audienceId: AudienceId;
41
+ readonly delta: TreeDelta;
42
+ };
43
+ /**
44
+ * Everything a deployment needs to serve one page to more than one audience:
45
+ * the rules that sort readers, and the delta each audience earns.
46
+ *
47
+ * Both halves are **cacheable beside the base** (0263 clause 3), which is why
48
+ * they are one value rather than two lookups — a host caching the base and
49
+ * re-fetching the rules per request has paid for the call this record exists to
50
+ * avoid.
51
+ */
52
+ export type AudienceOverlay = {
53
+ readonly rules: readonly AudienceRule[];
54
+ readonly forms: readonly AudienceForm[];
55
+ };
56
+ export type ComposeError =
57
+ /** A rule matched an audience the overlay has no delta for. */
58
+ {
59
+ readonly code: "no-form";
60
+ readonly audienceId: AudienceId;
61
+ }
62
+ /** The base moved and this delta was authored against an older revision. */
63
+ | {
64
+ readonly code: "stale-form";
65
+ readonly audienceId: AudienceId;
66
+ readonly expected: number;
67
+ readonly actual: number;
68
+ }
69
+ /** The delta is for another page. */
70
+ | {
71
+ readonly code: "form-mismatch";
72
+ readonly audienceId: AudienceId;
73
+ readonly treeId: string;
74
+ }
75
+ /** The operations did not apply, or what they produced is not a tree. */
76
+ | {
77
+ readonly code: "unapplicable";
78
+ readonly audienceId: AudienceId;
79
+ readonly detail: string;
80
+ };
81
+ /** The tree this reader gets, and the audiences that made it that. */
82
+ export type ComposedTree = {
83
+ readonly tree: LoomTree;
84
+ /**
85
+ * In the order the rules gave them, which is the order the deltas were
86
+ * applied in. A caller names this on the signals the page sends, so that what
87
+ * was measured and what was served are the same claim.
88
+ */
89
+ readonly audiences: readonly AudienceId[];
90
+ };
91
+ export declare const describeComposeError: (error: ComposeError) => string;
92
+ /**
93
+ * The page this context earns, or why it cannot be served.
94
+ *
95
+ * **It refuses rather than falling back to the base, and that is the decision
96
+ * in this function.** A composition that quietly dropped a stale delta would
97
+ * serve the base tree to a reader the deployment has already decided is in
98
+ * `aud_eu`, and the signals that page sends would be filed under `aud_eu`
99
+ * anyway — so the comparison 0263 clause 5 exists for would be between one
100
+ * audience's form and another audience's *name over the base's form*. A
101
+ * measurement that is quietly wrong is worse than a page that is honestly
102
+ * missing, which is the same argument `origins` is closed by default on.
103
+ *
104
+ * It is all-or-nothing per request for the same reason: two matched deltas of
105
+ * which one applied is a form nobody authored, judged or asked for.
106
+ *
107
+ * A context matching nothing is **not** a failure — it is the base tree, which
108
+ * is what every deployment that has never heard of an audience is already
109
+ * being served.
110
+ */
111
+ export declare const composeTreeForContext: (base: LoomTree, overlay: AudienceOverlay, context: JsonObject | undefined) => Result<ComposedTree, ComposeError>;
112
+ //# sourceMappingURL=compose.d.ts.map
@@ -0,0 +1,134 @@
1
+ /**
2
+ * A page as the reader in front of it gets it: the base tree, plus the deltas
3
+ * the audiences they are in have earned.
4
+ *
5
+ * This is
6
+ * [0263](../../decisions/0263-a-page-is-a-base-tree-and-the-deltas-an-audience-earns.md)
7
+ * clause 4 — *base plus matched deltas, locally, with no call to the control
8
+ * plane* — and it is a **pure function of a tree, a set of rules and a
9
+ * context**, which is what lets it run on every request in the customer's own
10
+ * process beside the render it feeds.
11
+ *
12
+ * **What comes out is a projection of a revision and not a revision of its
13
+ * own.** The composed tree keeps the base's `treeId` and the base's `revision`,
14
+ * and nothing about it is appended anywhere. Three reasons, and the third is
15
+ * the one that decided it:
16
+ *
17
+ * - A revision is a thing the log can replay and attribute. A composition is
18
+ * derived from one, per request, from rules that may change between two
19
+ * requests; it has no author, no timestamp and no place in the history.
20
+ * - Bumping the number would make a reader's revision depend on which audience
21
+ * they fell into, so two readers of the same published page would report
22
+ * different revisions for it.
23
+ * - **The measurement joins on it.** 0284 made a counter's identity
24
+ * `(application, audience, tree, revision)`. If a composition carried its own
25
+ * revision, the audience dimension and the revision dimension would move
26
+ * together and *compare these two audiences on this revision* — the whole
27
+ * point of serving two — would have nothing to compare.
28
+ *
29
+ * So the base revision is what a signal names, and the audience is what tells
30
+ * two forms of it apart. That is the shape 0284 already built the tables for.
31
+ */
32
+ import { err, ok, reduceResult } from "../result.js";
33
+ import { applyOperation } from "../tree/apply.js";
34
+ import { audiencesFor } from "./rule.js";
35
+ export const describeComposeError = (error) => {
36
+ switch (error.code) {
37
+ case "no-form":
38
+ return `${error.audienceId} matched and has no delta`;
39
+ case "stale-form":
40
+ return `${error.audienceId}'s delta is against revision ${error.expected}, the page is at ${error.actual}`;
41
+ case "form-mismatch":
42
+ return `${error.audienceId}'s delta is for ${error.treeId}`;
43
+ case "unapplicable":
44
+ return `${error.audienceId}'s delta did not apply: ${error.detail}`;
45
+ }
46
+ };
47
+ const formFor = (overlay, audienceId) => {
48
+ const form = overlay.forms.find((candidate) => candidate.audienceId === audienceId);
49
+ return form === undefined ? err({ code: "no-form", audienceId }) : ok(form);
50
+ };
51
+ /**
52
+ * One audience's operations, against the root as the audiences before it left
53
+ * it.
54
+ *
55
+ * **The revision is checked against the base and never against the accumulator**
56
+ * — every delta here was authored against the same published revision, so
57
+ * chaining `applyDelta` would refuse the second one for being one behind a
58
+ * number composition had just moved. `applyOperation` exists for exactly this:
59
+ * *one operation against one tree, with no delta around it*.
60
+ */
61
+ const advanceForm = (base, root, form) => {
62
+ if (form.delta.treeId !== base.treeId) {
63
+ return err({ code: "form-mismatch", audienceId: form.audienceId, treeId: form.delta.treeId });
64
+ }
65
+ if (form.delta.baseRevision !== base.revision) {
66
+ return err({
67
+ code: "stale-form",
68
+ audienceId: form.audienceId,
69
+ expected: form.delta.baseRevision,
70
+ actual: base.revision,
71
+ });
72
+ }
73
+ return reduceResult(form.delta.operations, root, (current, operation) => {
74
+ const applied = applyOperation(current, operation);
75
+ return applied.ok
76
+ ? applied
77
+ : err({
78
+ code: "unapplicable",
79
+ audienceId: form.audienceId,
80
+ detail: `${applied.error.code}`,
81
+ });
82
+ });
83
+ };
84
+ /**
85
+ * The page this context earns, or why it cannot be served.
86
+ *
87
+ * **It refuses rather than falling back to the base, and that is the decision
88
+ * in this function.** A composition that quietly dropped a stale delta would
89
+ * serve the base tree to a reader the deployment has already decided is in
90
+ * `aud_eu`, and the signals that page sends would be filed under `aud_eu`
91
+ * anyway — so the comparison 0263 clause 5 exists for would be between one
92
+ * audience's form and another audience's *name over the base's form*. A
93
+ * measurement that is quietly wrong is worse than a page that is honestly
94
+ * missing, which is the same argument `origins` is closed by default on.
95
+ *
96
+ * It is all-or-nothing per request for the same reason: two matched deltas of
97
+ * which one applied is a form nobody authored, judged or asked for.
98
+ *
99
+ * A context matching nothing is **not** a failure — it is the base tree, which
100
+ * is what every deployment that has never heard of an audience is already
101
+ * being served.
102
+ */
103
+ export const composeTreeForContext = (base, overlay, context) => {
104
+ const audiences = audiencesFor(overlay.rules, context);
105
+ if (audiences.length === 0)
106
+ return ok({ tree: base, audiences });
107
+ const advanced = reduceResult(audiences, base.root, (root, audienceId) => {
108
+ const form = formFor(overlay, audienceId);
109
+ return form.ok ? advanceForm(base, root, form.value) : form;
110
+ });
111
+ if (!advanced.ok)
112
+ return advanced;
113
+ const root = advanced.value;
114
+ if (root.kind !== "element") {
115
+ return err({
116
+ code: "unapplicable",
117
+ audienceId: audiences[audiences.length - 1],
118
+ detail: `root became a ${root.kind} node`,
119
+ });
120
+ }
121
+ /*
122
+ * No invariant check here, and it was a defensive one until a planted
123
+ * mutation showed nothing could reach it. Two deltas each judged against the
124
+ * base on its own are the one place in this repository where independently
125
+ * authored operations meet, so the fear was a pair that each insert the same
126
+ * node id and together make a tree with two of one id. `insert` already
127
+ * refuses a node whose id the tree holds, so the second one fails as
128
+ * `duplicate-node-id` and never gets far enough to make the tree it would
129
+ * have invalidated — which is the only invariant `validateTreeInvariants`
130
+ * has. Written down because the next reader will have the same fear.
131
+ */
132
+ return ok({ tree: { ...base, root }, audiences });
133
+ };
134
+ //# sourceMappingURL=compose.js.map
@@ -0,0 +1,14 @@
1
+ /**
2
+ * An `AudienceOverlayStore` in two `Map`s, for a test and for a deployment with
3
+ * no database.
4
+ *
5
+ * The reference implementation, on the terms `memory.ts` and `memoryPolicyLog`
6
+ * already set, and it carries the same warning they do: a `Map` keeps nothing
7
+ * across a process, so on the serverless hosts §3 targets it keeps nothing at
8
+ * all. What it is honestly for is the suite, a lesson, and a deployment holding
9
+ * its forms in a module — which is the thing 0359 clause 6 said already
10
+ * satisfied the seam.
11
+ */
12
+ import { type AudienceOverlayStore } from "./overlay-store.js";
13
+ export declare const memoryAudienceOverlayStore: () => AudienceOverlayStore;
14
+ //# sourceMappingURL=memory.d.ts.map
@@ -0,0 +1,71 @@
1
+ /**
2
+ * An `AudienceOverlayStore` in two `Map`s, for a test and for a deployment with
3
+ * no database.
4
+ *
5
+ * The reference implementation, on the terms `memory.ts` and `memoryPolicyLog`
6
+ * already set, and it carries the same warning they do: a `Map` keeps nothing
7
+ * across a process, so on the serverless hosts §3 targets it keeps nothing at
8
+ * all. What it is honestly for is the suite, a lesson, and a deployment holding
9
+ * its forms in a module — which is the thing 0359 clause 6 said already
10
+ * satisfied the seam.
11
+ */
12
+ import { err, ok } from "../result.js";
13
+ import { audienceFormListingsOf, audienceOverlayOf, audienceRulesOutcomeOf, clampAudienceRuleHistoryLimit, servedFormsOf, withdrawnFormOf, } from "./overlay-store.js";
14
+ export const memoryAudienceOverlayStore = () => {
15
+ /**
16
+ * The whole log rather than its head, because the head is a view over it and
17
+ * this is the implementation the contract calls the reference: a `Map` of
18
+ * current rules would satisfy every read and quietly stop being a record.
19
+ */
20
+ const rules = new Map();
21
+ const forms = new Map();
22
+ const headOf = (treeId) => {
23
+ const log = rules.get(treeId) ?? [];
24
+ return log[log.length - 1];
25
+ };
26
+ /** Ascending by id, so two reads of an unchanged page answer in one order. */
27
+ const formsOf = (treeId) => [...(forms.get(treeId)?.values() ?? [])].sort((left, right) => left.audienceId.localeCompare(right.audienceId));
28
+ return {
29
+ overlay: async (treeId) => ok(audienceOverlayOf(headOf(treeId), servedFormsOf(formsOf(treeId)))),
30
+ rules: async (treeId) => ok(headOf(treeId)),
31
+ history: async (treeId, request) => ok([...(rules.get(treeId) ?? [])]
32
+ .reverse()
33
+ .slice(0, clampAudienceRuleHistoryLimit(request?.limit))),
34
+ forms: async (treeId) => ok(audienceFormListingsOf(formsOf(treeId))),
35
+ recordRules: async (treeId, request) => {
36
+ const outcome = audienceRulesOutcomeOf(treeId, request, headOf(treeId));
37
+ if (!outcome.ok || outcome.value.outcome === "unchanged")
38
+ return outcome;
39
+ rules.set(treeId, [...(rules.get(treeId) ?? []), outcome.value.revision]);
40
+ return outcome;
41
+ },
42
+ setForm: async (treeId, request) => {
43
+ if (request.delta.treeId !== treeId) {
44
+ return err({
45
+ code: "tree-mismatch",
46
+ treeId,
47
+ delta: request.delta.treeId,
48
+ });
49
+ }
50
+ /**
51
+ * `withdrawn: undefined` and not a carried-over value: writing a form is
52
+ * putting it back into service, and this is the one call that undoes a
53
+ * withdrawal (0403).
54
+ */
55
+ const stored = { treeId, ...request, withdrawn: undefined };
56
+ const held = forms.get(treeId) ?? new Map();
57
+ held.set(request.audienceId, stored);
58
+ forms.set(treeId, held);
59
+ return ok(stored);
60
+ },
61
+ withdrawForm: async (treeId, request) => {
62
+ const held = forms.get(treeId)?.get(request.audienceId);
63
+ if (held === undefined)
64
+ return ok(undefined);
65
+ const stored = withdrawnFormOf(held, request);
66
+ forms.get(treeId)?.set(request.audienceId, stored);
67
+ return ok(stored);
68
+ },
69
+ };
70
+ };
71
+ //# sourceMappingURL=memory.js.map
@@ -0,0 +1,343 @@
1
+ /**
2
+ * Custody of the two things a deployment needs to serve one page to more than
3
+ * one audience: the **rules** that sort readers, and the **form** each audience
4
+ * earns.
5
+ *
6
+ * [0359](../../decisions/0359-an-audience-rule-is-a-conjunction-of-scalar-clauses-and-a-composed-page-is-a-projection-of-a-revision.md)
7
+ * clause 6 left this out on purpose — *`composingTreeSourceFromStore` takes an
8
+ * `AudienceOverlaySource`, a seam and not a table* — so the composition could
9
+ * be built, tested and reviewed without a schema change under it. This is the
10
+ * table the seam was waiting for, and it is 0263's store dimension.
11
+ *
12
+ * **The rules are a log and the forms are rows, and the asymmetry is the
13
+ * decision in this file.** A rule decides which readers get which form, so
14
+ * editing one changes what every reader in that audience sees — without
15
+ * touching the page, its delta, or its log. Kept as a mutable row, that change
16
+ * would leave **no record anywhere**: the one thing Loom exists to make
17
+ * impossible. So a rule list is appended to, attributed and dense, exactly as
18
+ * the policy log is and for the same reason (0200). A form is a document being
19
+ * worked on; its history is the proposal that produced it, and a second log of
20
+ * every keystroke on it would be a record of drafting rather than of deciding.
21
+ *
22
+ * Nothing here evaluates a rule. `rule.ts` does that, in the customer's own
23
+ * process, over a context that never leaves it (0262) — this module only keeps
24
+ * what that evaluation is handed.
25
+ */
26
+ import { type TreeId } from "../ids.js";
27
+ import { type Result } from "../result.js";
28
+ import { type TreeDelta } from "../tree/delta.js";
29
+ import { type AudienceId } from "./audience.js";
30
+ import type { AudienceForm, AudienceOverlay } from "./compose.js";
31
+ import { type AudienceRule } from "./rule.js";
32
+ /**
33
+ * One recorded state of a page's audience rules.
34
+ *
35
+ * `rules` is an **array and not a set of rows with a position**, which is the
36
+ * whole reason this record exists rather than a table of clauses. 0359 clause 3
37
+ * makes the order load-bearing — the last matching rule wins a contested node —
38
+ * and an order expressed as a column is an order two writers can half-apply: a
39
+ * reorder becomes several row updates, and a reader arriving between two of them
40
+ * is served a precedence nobody authored. An array is one value, written once.
41
+ *
42
+ * `revision` starts at 1 and is dense, so it is also the number of times this
43
+ * page's rules have been edited.
44
+ */
45
+ export type AudienceRuleRevision = {
46
+ readonly treeId: TreeId;
47
+ readonly revision: number;
48
+ readonly rules: readonly AudienceRule[];
49
+ /** Who made these the rules (0200). Never absent: a rule nobody can be named for is not a decision. */
50
+ readonly actor: string;
51
+ readonly recordedAt: string;
52
+ };
53
+ /**
54
+ * Who took a form out of service, and when.
55
+ *
56
+ * Its own shape rather than two nullable fields on the row, so *withdrawn* is
57
+ * one thing a caller can test instead of a pair that can half-arrive. A form is
58
+ * either served or it is withdrawn by somebody at a time; there is no third
59
+ * state where one of those is known and the other is not.
60
+ */
61
+ export type AudienceFormWithdrawal = {
62
+ /** The person who undid the change, or `Loom` for a rebuild (0403). */
63
+ readonly actor: string;
64
+ readonly at: string;
65
+ };
66
+ /** One audience's delta, as the store keeps it. */
67
+ export type StoredAudienceForm = {
68
+ readonly treeId: TreeId;
69
+ readonly audienceId: AudienceId;
70
+ readonly delta: TreeDelta;
71
+ readonly actor: string;
72
+ readonly authoredAt: string;
73
+ /**
74
+ * Absent while this form is the one its audience is served, which is what
75
+ * every form `setForm` writes is, and what every form stored before
76
+ * withdrawal existed is (0403).
77
+ */
78
+ readonly withdrawn: AudienceFormWithdrawal | undefined;
79
+ };
80
+ /**
81
+ * What a screen listing a page's audiences needs, **without the deltas**.
82
+ *
83
+ * The reading 0359's consequences name: *a base edit stales every audience
84
+ * delta*, so the first question anybody asks of a page with audiences is which
85
+ * of its forms are behind. Answering that from `overlay` means loading every
86
+ * delta to read one number off each — on a screen whose job is to say which of
87
+ * them is unusable.
88
+ *
89
+ * It says `baseRevision` and not *stale*, because staleness is a comparison
90
+ * against the page's head and this store holds no pages. The caller holding
91
+ * both numbers is the one that can say it.
92
+ */
93
+ export type AudienceFormListing = {
94
+ readonly audienceId: AudienceId;
95
+ readonly baseRevision: number;
96
+ readonly actor: string;
97
+ readonly authoredAt: string;
98
+ /**
99
+ * Set where this form has been taken out of service, so a screen listing a
100
+ * page's segments can say *withdrawn by Ana* rather than showing a form the
101
+ * page is not serving as though it were (0403).
102
+ *
103
+ * **The listing keeps withdrawn forms and `overlay` drops them**, and the
104
+ * asymmetry is deliberate: the render path must not apply one, and the screen
105
+ * whose job is to say what happened to it must still see it.
106
+ */
107
+ readonly withdrawn: AudienceFormWithdrawal | undefined;
108
+ };
109
+ export type AudienceOverlayError =
110
+ /**
111
+ * Somebody else recorded rules for this page while this caller was editing
112
+ * the ones they read. Nothing was written.
113
+ */
114
+ {
115
+ readonly code: "out-of-date";
116
+ readonly treeId: TreeId;
117
+ readonly expected: number;
118
+ readonly current: number;
119
+ }
120
+ /**
121
+ * The delta is for another page.
122
+ *
123
+ * Refused at the write rather than stored, because `composeTreeForContext`
124
+ * refuses it at every render: a form under one page carrying a delta for
125
+ * another is a row that can never be served to anybody, and accepting it
126
+ * trades a fault a person sees now for a page that is quietly unavailable
127
+ * later.
128
+ */
129
+ | {
130
+ readonly code: "tree-mismatch";
131
+ readonly treeId: TreeId;
132
+ readonly delta: string;
133
+ }
134
+ /** A row the current code cannot parse, which is a row an older one wrote. */
135
+ | {
136
+ readonly code: "unreadable";
137
+ readonly treeId: TreeId;
138
+ readonly detail: string;
139
+ } | {
140
+ readonly code: "unavailable";
141
+ readonly detail: string;
142
+ };
143
+ export declare const describeAudienceOverlayError: (error: AudienceOverlayError) => string;
144
+ /**
145
+ * A row on the way out, checked rather than cast — the boundary every stored
146
+ * shape in this repository crosses the same way. These two outlive the code
147
+ * that wrote them by more than most: a rule is edited rarely and read on every
148
+ * request for as long as the page is published.
149
+ */
150
+ export declare const parseAudienceRuleRevision: (row: unknown, treeId: TreeId) => Result<AudienceRuleRevision, AudienceOverlayError>;
151
+ export declare const parseStoredAudienceForm: (row: unknown, treeId: TreeId) => Result<StoredAudienceForm, AudienceOverlayError>;
152
+ export type AudienceRuleHistoryRequest = {
153
+ /** Clamped by the implementation — see `clampAudienceRuleHistoryLimit`. */
154
+ readonly limit?: number;
155
+ };
156
+ export type RecordAudienceRulesRequest = {
157
+ readonly rules: readonly AudienceRule[];
158
+ readonly actor: string;
159
+ readonly recordedAt: string;
160
+ /**
161
+ * The revision the caller believes is current, or `0` for *this page has no
162
+ * rules yet*.
163
+ *
164
+ * Optional, and the difference is which failure the caller is protected from.
165
+ * Omitted, a concurrent recorder wins and this one appends after it. Named, a
166
+ * recorder that lost the race is told so and nothing is written — which is
167
+ * what a rule editor wants, because the person was reordering a list that is
168
+ * no longer the list.
169
+ */
170
+ readonly expectedRevision?: number;
171
+ };
172
+ /**
173
+ * What recording did, which is not always *appended*.
174
+ *
175
+ * Two outcomes rather than the policy log's three. *First* and *changed* are
176
+ * `revision === 1` and are not worth a case a caller has to handle; *unchanged*
177
+ * is, because without it a screen that saves on blur writes a revision per
178
+ * visit and the log stops meaning *somebody changed who sees what*.
179
+ *
180
+ * Compared against the head alone, never against the whole history: rules
181
+ * edited to B and back to A **is** a change somebody made at a time, and
182
+ * recording it has to append.
183
+ */
184
+ export type AudienceRulesRecorded = {
185
+ readonly outcome: "recorded";
186
+ readonly revision: AudienceRuleRevision;
187
+ } | {
188
+ readonly outcome: "unchanged";
189
+ readonly revision: AudienceRuleRevision;
190
+ };
191
+ export type AuthorAudienceFormRequest = {
192
+ readonly audienceId: AudienceId;
193
+ readonly delta: TreeDelta;
194
+ readonly actor: string;
195
+ readonly authoredAt: string;
196
+ };
197
+ export type WithdrawAudienceFormRequest = {
198
+ readonly audienceId: AudienceId;
199
+ /** Who took it out of service. Never absent, for the reason `actor` never is. */
200
+ readonly actor: string;
201
+ readonly withdrawnAt: string;
202
+ };
203
+ /**
204
+ * How much of a page's rule history one read answers.
205
+ *
206
+ * Bounded, because every read in this store is (0025's rule, as `store.ts`
207
+ * states it: *no caller can ask a store for everything it holds, whether by
208
+ * naming a large limit or by naming none*). Unpaged, which `ProjectStore.list`
209
+ * already is: a page's rules are edited rarely, the newest edits are the ones a
210
+ * screen shows, and a cursor is machinery that would be written now and first
211
+ * exercised by nobody. **Reaching past the limit is not offered** — the rows are
212
+ * there, and the read that walks them is for whoever first needs it.
213
+ */
214
+ export declare const DEFAULT_AUDIENCE_RULE_HISTORY_LIMIT = 25;
215
+ export declare const MAX_AUDIENCE_RULE_HISTORY_LIMIT = 100;
216
+ export declare const clampAudienceRuleHistoryLimit: (limit: number | undefined) => number;
217
+ /**
218
+ * What a `record` call should do, given the head it would append after.
219
+ *
220
+ * Shared rather than written per backend, for the reason `recordOutcomeOf` is:
221
+ * the staleness check and *what counts as unchanged* are the contract, not an
222
+ * implementation detail, so two backends cannot disagree about whether a save
223
+ * with nothing in it is an edit.
224
+ */
225
+ export declare const audienceRulesOutcomeOf: (treeId: TreeId, request: RecordAudienceRulesRequest, head: AudienceRuleRevision | undefined) => Result<AudienceRulesRecorded, AudienceOverlayError>;
226
+ /**
227
+ * The read half, for the render path.
228
+ *
229
+ * `overlay` is what `audienceOverlaySourceFromStore` hands the composition, and
230
+ * it is answered **whole** — rules and forms in one call — because both halves
231
+ * are cacheable beside the base (0263 clause 3) and a host re-fetching the
232
+ * rules per request has paid for the call this whole design exists to avoid.
233
+ *
234
+ * **Withdrawn forms are not in it** (0403). `overlay` is the render path's read
235
+ * and a withdrawn form is one no reader is served, so dropping it here is what
236
+ * makes undoing a segment's last change take effect — rather than every caller
237
+ * of this seam having to remember to.
238
+ *
239
+ * **A page with no rules is not a missing page.** It answers an empty overlay,
240
+ * which composes to the base, which is what every deployment that has never
241
+ * heard of an audience is already being served. There is no `not-found` here
242
+ * for that reason: this store does not know which pages exist, only which of
243
+ * them somebody has written rules for.
244
+ */
245
+ export interface AudienceOverlayReader {
246
+ readonly overlay: (treeId: TreeId) => Promise<Result<AudienceOverlay, AudienceOverlayError>>;
247
+ /** The current rules with their revision and author, for a screen editing them. */
248
+ readonly rules: (treeId: TreeId) => Promise<Result<AudienceRuleRevision | undefined, AudienceOverlayError>>;
249
+ /**
250
+ * The edits this page's rules have had, **newest first**.
251
+ *
252
+ * The read that makes the log a record rather than an accumulation. Without
253
+ * it, keeping every revision is unobservable from outside — a planted
254
+ * mutation that overwrote the log instead of appending to it changed nothing
255
+ * any caller could see, which is the same emptiness the composition's removed
256
+ * invariant check had. A record of who changed who sees what that nobody can
257
+ * read is not a record.
258
+ */
259
+ readonly history: (treeId: TreeId, request?: AudienceRuleHistoryRequest) => Promise<Result<readonly AudienceRuleRevision[], AudienceOverlayError>>;
260
+ /**
261
+ * Every form this page holds, **withdrawn ones included**, with no deltas.
262
+ *
263
+ * The listing and `overlay` part company here, for one reason: a withdrawn
264
+ * form is not served and is still a thing that happened to this page, so the
265
+ * screen that says what happened to it has to be able to see one. A caller
266
+ * deciding what to render reads `overlay`; a caller deciding what to *show a
267
+ * person about the page* reads this (0403).
268
+ */
269
+ readonly forms: (treeId: TreeId) => Promise<Result<readonly AudienceFormListing[], AudienceOverlayError>>;
270
+ }
271
+ /**
272
+ * Four reads and three writes, and **still no delete**, which this store shares
273
+ * with every other one here for a reason of its own: an audience stops being
274
+ * served by leaving the rules, or by having its form withdrawn — never by
275
+ * having its row removed. The form then matches nobody and costs a row, and the
276
+ * day it is wanted again the work is still there. A delete would make *we
277
+ * stopped serving this* and *we threw the work away* one button.
278
+ *
279
+ * **`withdrawForm` is the third write and it is not a delete**
280
+ * ([0403](../../decisions/0403-a-segments-form-is-withdrawn-by-somebody-at-a-time-and-its-work-is-kept.md)).
281
+ * 0376 clause 4 answered *may a form be removed* with no, and both of its
282
+ * reasons are kept here: the row stays, carrying the delta it held, and who
283
+ * took it out of service is on it. What 0376 did not cover is the act
284
+ * `Loom portal` needed — undoing the **last** change accepted for one segment,
285
+ * where rebuilding the form with one change fewer leaves a form with no
286
+ * operations and a `TreeDelta` must have at least one.
287
+ */
288
+ export interface AudienceOverlayStore extends AudienceOverlayReader {
289
+ readonly recordRules: (treeId: TreeId, request: RecordAudienceRulesRequest) => Promise<Result<AudienceRulesRecorded, AudienceOverlayError>>;
290
+ /**
291
+ * The form this audience earns, replacing whatever it had.
292
+ *
293
+ * An upsert rather than an append: a form is a document being worked on, and
294
+ * rebasing it onto a moved base is the ordinary thing that happens to it.
295
+ */
296
+ readonly setForm: (treeId: TreeId, request: AuthorAudienceFormRequest) => Promise<Result<StoredAudienceForm, AudienceOverlayError>>;
297
+ /**
298
+ * Take this audience's form out of service, keeping it and saying who did.
299
+ *
300
+ * Answers the row as it now stands, or `undefined` where the page has no
301
+ * form for that audience — **which is not an error**: the caller undoing a
302
+ * change wants that segment served the base, and a page that is already
303
+ * serving it the base is in the state being asked for. A caller that has to
304
+ * tell *withdrew one* from *there was none* reads which it got.
305
+ *
306
+ * Withdrawing a form that is already withdrawn restamps it with the second
307
+ * caller, for the reason `setForm` is an upsert: the alternative is an error
308
+ * code for an act whose outcome is the one asked for.
309
+ */
310
+ readonly withdrawForm: (treeId: TreeId, request: WithdrawAudienceFormRequest) => Promise<Result<StoredAudienceForm | undefined, AudienceOverlayError>>;
311
+ }
312
+ /**
313
+ * The overlay a reader of the two halves assembles, shared so the backends
314
+ * cannot disagree about what *whole* means.
315
+ */
316
+ export declare const audienceOverlayOf: (head: AudienceRuleRevision | undefined, forms: readonly AudienceForm[]) => AudienceOverlay;
317
+ /**
318
+ * The forms the render path is given: every row that has not been withdrawn,
319
+ * without its attribution.
320
+ *
321
+ * **Shared for the reason `audienceRulesOutcomeOf` is.** Which rows compose is
322
+ * the contract and not an implementation detail, and a backend that answered a
323
+ * withdrawn form would serve a segment a change somebody undid — the exact
324
+ * fault 0403 exists to close, arriving as a disagreement between two stores
325
+ * that are each green against their own expectations.
326
+ */
327
+ export declare const servedFormsOf: (stored: readonly StoredAudienceForm[]) => readonly AudienceForm[];
328
+ /**
329
+ * The listing a screen gets: **every** row, withdrawn ones included, with the
330
+ * deltas left behind (0376).
331
+ */
332
+ export declare const audienceFormListingsOf: (stored: readonly StoredAudienceForm[]) => readonly AudienceFormListing[];
333
+ /**
334
+ * The row a withdrawal leaves, given the one it found.
335
+ *
336
+ * Shared so neither backend can decide on its own that a withdrawal also
337
+ * rewrites `actor` or `authoredAt`. It does not: those two say who authored the
338
+ * form, and overwriting them with the person who withdrew it would lose the
339
+ * attribution 0376 clause 1 keeps — and make *who wrote this* unanswerable the
340
+ * moment somebody took it out of service.
341
+ */
342
+ export declare const withdrawnFormOf: (held: StoredAudienceForm, request: WithdrawAudienceFormRequest) => StoredAudienceForm;
343
+ //# sourceMappingURL=overlay-store.d.ts.map