@jam-overture/loom 0.1.0 → 0.2.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 (290) hide show
  1. package/README.md +3 -1
  2. package/dist/application/application.d.ts +109 -0
  3. package/dist/application/application.js +97 -0
  4. package/dist/application/memory.d.ts +20 -0
  5. package/dist/application/memory.js +79 -0
  6. package/dist/application/store.d.ts +101 -0
  7. package/dist/application/store.js +25 -0
  8. package/dist/audience/audience.d.ts +36 -0
  9. package/dist/audience/audience.js +41 -0
  10. package/dist/cli/templates.js +19 -0
  11. package/dist/data/plan.js +0 -0
  12. package/dist/data/resolution.d.ts +23 -1
  13. package/dist/data/resolve.d.ts +30 -3
  14. package/dist/data/resolve.js +11 -3
  15. package/dist/ids.d.ts +10 -0
  16. package/dist/ids.js +11 -1
  17. package/dist/index.d.ts +1 -0
  18. package/dist/index.js +1 -0
  19. package/dist/patch.d.ts +54 -0
  20. package/dist/patch.js +44 -0
  21. package/dist/project/closing.d.ts +51 -0
  22. package/dist/project/closing.js +53 -0
  23. package/dist/project/memory.d.ts +20 -0
  24. package/dist/project/memory.js +97 -0
  25. package/dist/project/project.d.ts +90 -0
  26. package/dist/project/project.js +91 -0
  27. package/dist/project/store.d.ts +135 -0
  28. package/dist/project/store.js +41 -0
  29. package/dist/registered.d.ts +64 -0
  30. package/dist/registered.js +118 -0
  31. package/dist/render/behaviour-adjust.d.ts +11 -19
  32. package/dist/render/behaviour-adjust.js +75 -21
  33. package/dist/render/behaviour-present.d.ts +8 -0
  34. package/dist/render/behaviour-present.js +57 -6
  35. package/dist/render/behaviour.d.ts +98 -17
  36. package/dist/render/behaviour.js +91 -26
  37. package/dist/render/control-name.d.ts +68 -0
  38. package/dist/render/control-name.js +37 -0
  39. package/dist/render/diagnostics.d.ts +72 -0
  40. package/dist/render/diagnostics.js +7 -0
  41. package/dist/render/index.d.ts +2 -0
  42. package/dist/render/index.js +2 -0
  43. package/dist/render/reads.d.ts +11 -0
  44. package/dist/render/reads.js +12 -1
  45. package/dist/render/render.js +102 -7
  46. package/dist/render/slots.d.ts +52 -0
  47. package/dist/render/slots.js +24 -0
  48. package/dist/render/theme.d.ts +54 -1
  49. package/dist/render/theme.js +23 -1
  50. package/dist/render/unshown.d.ts +152 -0
  51. package/dist/render/unshown.js +80 -0
  52. package/dist/runtime/analysis.d.ts +94 -9
  53. package/dist/runtime/analysis.js +54 -9
  54. package/dist/runtime/assessment.d.ts +36 -2
  55. package/dist/runtime/assessment.js +27 -2
  56. package/dist/runtime/checks.d.ts +148 -0
  57. package/dist/runtime/checks.js +112 -0
  58. package/dist/runtime/disposition.d.ts +96 -0
  59. package/dist/runtime/disposition.js +46 -0
  60. package/dist/runtime/gate.js +22 -0
  61. package/dist/runtime/index.d.ts +3 -0
  62. package/dist/runtime/index.js +3 -0
  63. package/dist/runtime/irreversibility.d.ts +64 -0
  64. package/dist/runtime/irreversibility.js +45 -0
  65. package/dist/runtime/pipeline.d.ts +43 -0
  66. package/dist/runtime/pipeline.js +10 -2
  67. package/dist/runtime/policy-change.d.ts +93 -0
  68. package/dist/runtime/policy-change.js +299 -0
  69. package/dist/runtime/policy-log.d.ts +406 -0
  70. package/dist/runtime/policy-log.js +285 -0
  71. package/dist/runtime/reversibility.d.ts +11 -9
  72. package/dist/runtime/stakes.d.ts +129 -1
  73. package/dist/runtime/stakes.js +240 -26
  74. package/dist/runtime/vocabulary.d.ts +164 -7
  75. package/dist/runtime/vocabulary.js +181 -8
  76. package/dist/sdk/audit.d.ts +174 -3
  77. package/dist/sdk/audit.js +176 -17
  78. package/dist/sdk/catalogue.d.ts +9 -1
  79. package/dist/sdk/conformance.d.ts +37 -3
  80. package/dist/sdk/conformance.js +25 -4
  81. package/dist/sdk/definition.d.ts +65 -0
  82. package/dist/sdk/definition.js +22 -0
  83. package/dist/sdk/registry.d.ts +29 -2
  84. package/dist/sdk/registry.js +63 -1
  85. package/dist/signals/action-change.d.ts +507 -0
  86. package/dist/signals/action-change.js +265 -0
  87. package/dist/signals/action.d.ts +331 -0
  88. package/dist/signals/action.js +182 -0
  89. package/dist/signals/applied-window.contract.d.ts +23 -0
  90. package/dist/signals/applied-window.contract.js +160 -0
  91. package/dist/signals/arriving.d.ts +210 -0
  92. package/dist/signals/arriving.js +133 -0
  93. package/dist/signals/audiences.d.ts +528 -0
  94. package/dist/signals/audiences.js +255 -0
  95. package/dist/signals/broadcast.d.ts +8 -2
  96. package/dist/signals/broadcast.js +58 -8
  97. package/dist/signals/change.d.ts +378 -0
  98. package/dist/signals/change.js +327 -0
  99. package/dist/signals/collect.d.ts +41 -0
  100. package/dist/signals/collect.js +88 -7
  101. package/dist/signals/copy-change.d.ts +553 -0
  102. package/dist/signals/copy-change.js +377 -0
  103. package/dist/signals/copy.d.ts +337 -0
  104. package/dist/signals/copy.js +211 -0
  105. package/dist/signals/counters.d.ts +46 -0
  106. package/dist/signals/counters.js +102 -0
  107. package/dist/signals/deliver.d.ts +23 -4
  108. package/dist/signals/deliver.js +34 -6
  109. package/dist/signals/deployment-change.d.ts +371 -0
  110. package/dist/signals/deployment-change.js +268 -0
  111. package/dist/signals/deployment.d.ts +265 -0
  112. package/dist/signals/deployment.js +152 -0
  113. package/dist/signals/door.d.ts +92 -0
  114. package/dist/signals/door.js +53 -0
  115. package/dist/signals/fold.d.ts +10 -0
  116. package/dist/signals/fold.js +5 -1
  117. package/dist/signals/form-action.d.ts +302 -0
  118. package/dist/signals/form-action.js +169 -0
  119. package/dist/signals/form-copy.d.ts +523 -0
  120. package/dist/signals/form-copy.js +346 -0
  121. package/dist/signals/forms.d.ts +247 -0
  122. package/dist/signals/forms.js +147 -0
  123. package/dist/signals/funnel-change.d.ts +548 -0
  124. package/dist/signals/funnel-change.js +361 -0
  125. package/dist/signals/funnel.d.ts +532 -0
  126. package/dist/signals/funnel.js +216 -0
  127. package/dist/signals/health.d.ts +497 -0
  128. package/dist/signals/health.js +361 -0
  129. package/dist/signals/index.d.ts +41 -0
  130. package/dist/signals/index.js +41 -0
  131. package/dist/signals/ingest.d.ts +56 -1
  132. package/dist/signals/ingest.js +91 -1
  133. package/dist/signals/journal.d.ts +11 -0
  134. package/dist/signals/kinds.d.ts +8 -6
  135. package/dist/signals/kinds.js +14 -6
  136. package/dist/signals/library-action.d.ts +430 -0
  137. package/dist/signals/library-action.js +336 -0
  138. package/dist/signals/library-change.d.ts +477 -0
  139. package/dist/signals/library-change.js +335 -0
  140. package/dist/signals/library-copy-change.d.ts +498 -0
  141. package/dist/signals/library-copy-change.js +476 -0
  142. package/dist/signals/library-pace.d.ts +319 -0
  143. package/dist/signals/library-pace.js +305 -0
  144. package/dist/signals/library-reach-change.d.ts +636 -0
  145. package/dist/signals/library-reach-change.js +534 -0
  146. package/dist/signals/library-reach.d.ts +377 -0
  147. package/dist/signals/library-reach.js +227 -0
  148. package/dist/signals/library-word-reach-change.d.ts +567 -0
  149. package/dist/signals/library-word-reach-change.js +568 -0
  150. package/dist/signals/library.d.ts +306 -0
  151. package/dist/signals/library.js +178 -0
  152. package/dist/signals/memory.d.ts +9 -0
  153. package/dist/signals/memory.js +105 -14
  154. package/dist/signals/migrate.d.ts +17 -2
  155. package/dist/signals/migrate.js +122 -5
  156. package/dist/signals/notice.d.ts +334 -0
  157. package/dist/signals/notice.js +228 -0
  158. package/dist/signals/pace-change.d.ts +501 -0
  159. package/dist/signals/pace-change.js +310 -0
  160. package/dist/signals/pace.d.ts +296 -0
  161. package/dist/signals/pace.js +291 -0
  162. package/dist/signals/page-views.d.ts +365 -0
  163. package/dist/signals/page-views.js +218 -0
  164. package/dist/signals/parts.d.ts +344 -0
  165. package/dist/signals/parts.js +273 -0
  166. package/dist/signals/postgres.d.ts +16 -2
  167. package/dist/signals/postgres.js +390 -87
  168. package/dist/signals/progress.d.ts +212 -0
  169. package/dist/signals/progress.js +150 -0
  170. package/dist/signals/ratios.d.ts +108 -0
  171. package/dist/signals/ratios.js +40 -0
  172. package/dist/signals/reach.d.ts +309 -0
  173. package/dist/signals/reach.js +93 -0
  174. package/dist/signals/readable.d.ts +34 -0
  175. package/dist/signals/readable.js +34 -0
  176. package/dist/signals/readership.d.ts +381 -0
  177. package/dist/signals/readership.js +308 -0
  178. package/dist/signals/region-pages.d.ts +173 -0
  179. package/dist/signals/region-pages.js +62 -0
  180. package/dist/signals/region.d.ts +287 -0
  181. package/dist/signals/region.js +198 -0
  182. package/dist/signals/retention.d.ts +141 -0
  183. package/dist/signals/retention.js +58 -0
  184. package/dist/signals/rollup.d.ts +67 -3
  185. package/dist/signals/rollup.js +0 -0
  186. package/dist/signals/schema.d.ts +432 -1
  187. package/dist/signals/schema.js +157 -3
  188. package/dist/signals/signal.d.ts +237 -11
  189. package/dist/signals/signal.js +70 -10
  190. package/dist/signals/silence-census.d.ts +205 -0
  191. package/dist/signals/silence-census.js +87 -0
  192. package/dist/signals/silences.d.ts +848 -0
  193. package/dist/signals/silences.js +753 -0
  194. package/dist/signals/tally.d.ts +140 -11
  195. package/dist/signals/window-figures.d.ts +148 -0
  196. package/dist/signals/window-figures.js +42 -0
  197. package/dist/signals/window.d.ts +866 -0
  198. package/dist/signals/window.js +693 -0
  199. package/dist/signals/words.d.ts +24 -0
  200. package/dist/signals/words.js +24 -0
  201. package/dist/store/index.d.ts +19 -0
  202. package/dist/store/index.js +19 -0
  203. package/dist/store/memory.d.ts +2 -1
  204. package/dist/store/memory.js +48 -12
  205. package/dist/store/migrate.d.ts +80 -0
  206. package/dist/store/migrate.js +259 -7
  207. package/dist/store/postgres-applications.d.ts +4 -0
  208. package/dist/store/postgres-applications.js +197 -0
  209. package/dist/store/postgres-holds.d.ts +10 -1
  210. package/dist/store/postgres-holds.js +116 -101
  211. package/dist/store/postgres-policy-log.d.ts +14 -0
  212. package/dist/store/postgres-policy-log.js +240 -0
  213. package/dist/store/postgres-projects.d.ts +4 -0
  214. package/dist/store/postgres-projects.js +217 -0
  215. package/dist/store/postgres.d.ts +16 -1
  216. package/dist/store/postgres.js +59 -9
  217. package/dist/store/replay.d.ts +102 -1
  218. package/dist/store/replay.js +190 -19
  219. package/dist/store/reseed.d.ts +238 -0
  220. package/dist/store/reseed.js +308 -0
  221. package/dist/store/schema.d.ts +450 -2
  222. package/dist/store/schema.js +141 -5
  223. package/dist/store/store.d.ts +29 -6
  224. package/dist/submit/resolve.js +2 -1
  225. package/dist/telemetry/calibration.d.ts +25 -0
  226. package/dist/telemetry/calibration.js +27 -1
  227. package/dist/telemetry/event.d.ts +391 -33
  228. package/dist/telemetry/event.js +84 -20
  229. package/dist/telemetry/index.d.ts +1 -0
  230. package/dist/telemetry/index.js +1 -0
  231. package/dist/telemetry/journal.d.ts +72 -3
  232. package/dist/telemetry/journal.js +9 -0
  233. package/dist/telemetry/lookup.d.ts +27 -0
  234. package/dist/telemetry/lookup.js +18 -0
  235. package/dist/telemetry/memory.js +23 -0
  236. package/dist/telemetry/migrate.js +22 -1
  237. package/dist/telemetry/postgres.d.ts +10 -1
  238. package/dist/telemetry/postgres.js +172 -90
  239. package/dist/telemetry/remeasure.d.ts +78 -0
  240. package/dist/telemetry/remeasure.js +83 -0
  241. package/dist/telemetry/retention.d.ts +2 -2
  242. package/dist/telemetry/schema.d.ts +17 -0
  243. package/dist/telemetry/schema.js +27 -1
  244. package/dist/telemetry/sink.d.ts +2 -2
  245. package/dist/testing/application-contract.d.ts +14 -0
  246. package/dist/testing/application-contract.js +270 -0
  247. package/dist/testing/contracts.d.ts +12 -7
  248. package/dist/testing/contracts.js +12 -7
  249. package/dist/testing/definitions.d.ts +78 -0
  250. package/dist/testing/definitions.js +134 -9
  251. package/dist/testing/doubles.d.ts +103 -0
  252. package/dist/testing/doubles.js +143 -0
  253. package/dist/testing/index.d.ts +2 -2
  254. package/dist/testing/index.js +2 -2
  255. package/dist/testing/journal-contract.js +140 -2
  256. package/dist/testing/model-contract.d.ts +110 -0
  257. package/dist/testing/model-contract.js +150 -0
  258. package/dist/testing/policy-log-contract.d.ts +26 -0
  259. package/dist/testing/policy-log-contract.js +344 -0
  260. package/dist/testing/project-contract.d.ts +14 -0
  261. package/dist/testing/project-contract.js +266 -0
  262. package/dist/testing/reader-signal-contract.d.ts +27 -2
  263. package/dist/testing/reader-signal-contract.js +475 -5
  264. package/dist/testing/store-contract.d.ts +7 -1
  265. package/dist/testing/store-contract.js +84 -3
  266. package/dist/theme/apply.d.ts +20 -1
  267. package/dist/theme/apply.js +5 -3
  268. package/dist/theme/derive.d.ts +22 -0
  269. package/dist/theme/derive.js +54 -1
  270. package/dist/theme/library.js +1 -1
  271. package/dist/theme/measure.d.ts +34 -0
  272. package/dist/theme/measure.js +30 -1
  273. package/dist/theme/palettes.js +7 -7
  274. package/dist/theme/ramp.d.ts +64 -0
  275. package/dist/theme/ramp.js +114 -0
  276. package/dist/theme/registry.d.ts +9 -0
  277. package/dist/theme/registry.js +11 -1
  278. package/dist/theme/separation.d.ts +97 -3
  279. package/dist/theme/separation.js +75 -0
  280. package/dist/tree/compare.d.ts +9 -0
  281. package/dist/tree/compare.js +18 -0
  282. package/dist/write/computed.d.ts +60 -0
  283. package/dist/write/computed.js +61 -0
  284. package/dist/write/held.d.ts +59 -0
  285. package/dist/write/index.d.ts +5 -2
  286. package/dist/write/index.js +5 -2
  287. package/dist/write/reseed.d.ts +151 -0
  288. package/dist/write/reseed.js +184 -0
  289. package/dist/write/revert.js +2 -16
  290. package/package.json +98 -19
package/README.md CHANGED
@@ -436,7 +436,9 @@ The runtime compiles to `dist/` and every entry point resolves there (0030), so
436
436
  the application consumes it as an ordinary Node package rather than as TypeScript
437
437
  source. `apps/loom` builds the runtime before its own typecheck and build,
438
438
  because a clean clone has no `dist` and a build order that is not written down is
439
- one that fails somewhere else.
439
+ one that fails somewhere else. Its `verify` runs the build first and then calls
440
+ `tsc` directly rather than `pnpm typecheck`, because the build has just compiled
441
+ the runtime and compiling it a second time bought nothing.
440
442
 
441
443
  ## Deploying
442
444
 
@@ -0,0 +1,109 @@
1
+ /**
2
+ * The thing a customer registers with Loom, and the unit everything is stored
3
+ * and governed under.
4
+ *
5
+ * A deployment used to be one registry, one policy source and one store wired
6
+ * at a composition root, with no identifier anywhere for the thing that owned
7
+ * them — there had only ever been one per process (0220). An application is
8
+ * that identifier, and every tree, revision, hold and signal sits inside one. A
9
+ * tree id is unique within its application and says nothing about any other.
10
+ *
11
+ * It is the third of three levels: an **account** holds **projects**, and a
12
+ * project holds **applications** (0269). The level above this one is a grouping
13
+ * and owns nothing yet, which is why nothing here defers to it but the
14
+ * `projectId` an application carries.
15
+ */
16
+ import { z } from "zod";
17
+ export declare const applicationIdSchema: z.ZodBranded<z.ZodString, "ApplicationId">;
18
+ export type ApplicationId = z.infer<typeof applicationIdSchema>;
19
+ /**
20
+ * A new application's id, minted when somebody registers one.
21
+ *
22
+ * Random rather than derived from the name: a name is editable and not unique,
23
+ * and an id that was derived from one would either change when it is renamed or
24
+ * preserve a name somebody wanted gone. It is also the value a person pastes
25
+ * into their own configuration, so it must not say anything about them.
26
+ */
27
+ export declare const newApplicationId: () => ApplicationId;
28
+ /**
29
+ * The application every row written before applications existed belongs to.
30
+ *
31
+ * Nothing is migrated by guessing (0260). The rows that exist belong to the
32
+ * deployment that wrote them, so they go into one application named for it rather
33
+ * than into a distribution somebody invented. It is also what a store
34
+ * built without an application uses, which is what keeps every existing caller —
35
+ * the demo, the documentation's worked examples, the eight thousand tests —
36
+ * meaning exactly what it meant before.
37
+ *
38
+ * **It is not a null.** Every read filters on it and every write sets it, so
39
+ * it is an application like any other; what makes it the default is only that it is
40
+ * the one a caller gets by saying nothing.
41
+ */
42
+ export declare const DEFAULT_APPLICATION_ID: ApplicationId;
43
+ /**
44
+ * What a deployment knows about one of its applications.
45
+ *
46
+ * Deliberately thin. The registry, the policy and the ingest credential are
47
+ * each their own concern with their own store — this is the row that says the
48
+ * application exists and what a person calls it, and nothing that another module
49
+ * already owns.
50
+ */
51
+ export declare const applicationSchema: z.ZodObject<{
52
+ applicationId: z.ZodBranded<z.ZodString, "ApplicationId">;
53
+ /**
54
+ * The project it is grouped under, which every application has exactly one
55
+ * of. The grouping is organisational and nothing else yet — a project owns
56
+ * no policy and no members, so nothing reads this but a screen deciding
57
+ * which heading to put the application under. When it does own something,
58
+ * this is the edge that inheritance travels along.
59
+ */
60
+ projectId: z.ZodBranded<z.ZodString, "ProjectId">;
61
+ /** What a person calls it. Not unique, not an identifier, and editable. */
62
+ name: z.ZodString;
63
+ createdAt: z.ZodString;
64
+ /**
65
+ * Where the application lives, when it has said so. Used to tell a reader
66
+ * which application they are looking at, and to decide which origin may
67
+ * post its readers' signals — that one exactly, when it is set (0298).
68
+ */
69
+ host: z.ZodOptional<z.ZodString>;
70
+ /**
71
+ * When it was closed, or absent while it is open (0289). See
72
+ * `Project.closedAt`, which this follows in every respect but one: an
73
+ * application is closed *by* its project closing, and is not reopened by
74
+ * its project reopening.
75
+ *
76
+ * A closed application takes no signals. That is enforced where ingest
77
+ * learns which application is posting, which is the host's door rather
78
+ * than this schema (0298).
79
+ */
80
+ closedAt: z.ZodOptional<z.ZodString>;
81
+ }, "strict", z.ZodTypeAny, {
82
+ name: string;
83
+ projectId: string & z.BRAND<"ProjectId">;
84
+ createdAt: string;
85
+ applicationId: string & z.BRAND<"ApplicationId">;
86
+ closedAt?: string | undefined;
87
+ host?: string | undefined;
88
+ }, {
89
+ name: string;
90
+ projectId: string;
91
+ createdAt: string;
92
+ applicationId: string;
93
+ closedAt?: string | undefined;
94
+ host?: string | undefined;
95
+ }>;
96
+ export type Application = z.infer<typeof applicationSchema>;
97
+ /**
98
+ * The application a store handle speaks for.
99
+ *
100
+ * A handle is scoped at construction rather than every method taking a
101
+ * application, which is the cheaper of the two shapes that were priced (0220):
102
+ * it leaves every signature in `@jam-overture/loom/store` alone, and
103
+ * it makes *spanning two applications* unexpressible rather than merely forbidden.
104
+ * A caller that wants two holds two handles.
105
+ */
106
+ export type StoreScope = {
107
+ readonly application?: ApplicationId;
108
+ };
109
+ //# sourceMappingURL=application.d.ts.map
@@ -0,0 +1,97 @@
1
+ /**
2
+ * The thing a customer registers with Loom, and the unit everything is stored
3
+ * and governed under.
4
+ *
5
+ * A deployment used to be one registry, one policy source and one store wired
6
+ * at a composition root, with no identifier anywhere for the thing that owned
7
+ * them — there had only ever been one per process (0220). An application is
8
+ * that identifier, and every tree, revision, hold and signal sits inside one. A
9
+ * tree id is unique within its application and says nothing about any other.
10
+ *
11
+ * It is the third of three levels: an **account** holds **projects**, and a
12
+ * project holds **applications** (0269). The level above this one is a grouping
13
+ * and owns nothing yet, which is why nothing here defers to it but the
14
+ * `projectId` an application carries.
15
+ */
16
+ import { z } from "zod";
17
+ import { idPattern } from "../grammar.js";
18
+ import { randomIdBody } from "../ids.js";
19
+ import { projectIdSchema } from "../project/project.js";
20
+ /*
21
+ * `app` and not `a`: every other id in `ids.ts` wears a single letter, and an
22
+ * application id is the one identifier here that a person reads off a screen
23
+ * and pastes into their own configuration — so it is spelled rather than
24
+ * initialled, like the hosts that do the same job. It carried `prj` until the
25
+ * hierarchy was settled on 12 October, when *project* turned out to name the
26
+ * grouping above this rather than this.
27
+ */
28
+ export const applicationIdSchema = z
29
+ .string()
30
+ .regex(idPattern("app"))
31
+ .brand();
32
+ /**
33
+ * A new application's id, minted when somebody registers one.
34
+ *
35
+ * Random rather than derived from the name: a name is editable and not unique,
36
+ * and an id that was derived from one would either change when it is renamed or
37
+ * preserve a name somebody wanted gone. It is also the value a person pastes
38
+ * into their own configuration, so it must not say anything about them.
39
+ */
40
+ export const newApplicationId = () => applicationIdSchema.parse(`app_${randomIdBody()}`);
41
+ /**
42
+ * The application every row written before applications existed belongs to.
43
+ *
44
+ * Nothing is migrated by guessing (0260). The rows that exist belong to the
45
+ * deployment that wrote them, so they go into one application named for it rather
46
+ * than into a distribution somebody invented. It is also what a store
47
+ * built without an application uses, which is what keeps every existing caller —
48
+ * the demo, the documentation's worked examples, the eight thousand tests —
49
+ * meaning exactly what it meant before.
50
+ *
51
+ * **It is not a null.** Every read filters on it and every write sets it, so
52
+ * it is an application like any other; what makes it the default is only that it is
53
+ * the one a caller gets by saying nothing.
54
+ */
55
+ export const DEFAULT_APPLICATION_ID = applicationIdSchema.parse("app_default");
56
+ /**
57
+ * What a deployment knows about one of its applications.
58
+ *
59
+ * Deliberately thin. The registry, the policy and the ingest credential are
60
+ * each their own concern with their own store — this is the row that says the
61
+ * application exists and what a person calls it, and nothing that another module
62
+ * already owns.
63
+ */
64
+ export const applicationSchema = z
65
+ .object({
66
+ applicationId: applicationIdSchema,
67
+ /**
68
+ * The project it is grouped under, which every application has exactly one
69
+ * of. The grouping is organisational and nothing else yet — a project owns
70
+ * no policy and no members, so nothing reads this but a screen deciding
71
+ * which heading to put the application under. When it does own something,
72
+ * this is the edge that inheritance travels along.
73
+ */
74
+ projectId: projectIdSchema,
75
+ /** What a person calls it. Not unique, not an identifier, and editable. */
76
+ name: z.string().min(1).max(200),
77
+ createdAt: z.string().datetime(),
78
+ /**
79
+ * Where the application lives, when it has said so. Used to tell a reader
80
+ * which application they are looking at, and to decide which origin may
81
+ * post its readers' signals — that one exactly, when it is set (0298).
82
+ */
83
+ host: z.string().min(1).max(253).optional(),
84
+ /**
85
+ * When it was closed, or absent while it is open (0289). See
86
+ * `Project.closedAt`, which this follows in every respect but one: an
87
+ * application is closed *by* its project closing, and is not reopened by
88
+ * its project reopening.
89
+ *
90
+ * A closed application takes no signals. That is enforced where ingest
91
+ * learns which application is posting, which is the host's door rather
92
+ * than this schema (0298).
93
+ */
94
+ closedAt: z.string().datetime().optional(),
95
+ })
96
+ .strict();
97
+ //# sourceMappingURL=application.js.map
@@ -0,0 +1,20 @@
1
+ import { type Application } from "./application.js";
2
+ import type { ApplicationStore } from "./store.js";
3
+ /**
4
+ * A `ApplicationStore` in a `Map`, for a test and for a deployment with no database.
5
+ *
6
+ * The counterpart to `memoryStore`, and it carries the same warning: a `Map`
7
+ * keeps nothing across a process, so on the serverless hosts §3 targets it
8
+ * keeps nothing at all. What it is honestly for is the suite, a lesson, and the
9
+ * first run of an application that has not been given a `DATABASE_URL` yet —
10
+ * where seeing one application called *your application* beats seeing an error.
11
+ *
12
+ * The listing sorts, and the first draft of this file did not — its comment
13
+ * claimed insertion order "happens to be oldest first", which confuses the
14
+ * order rows were *written* with the order they were *created*. An application
15
+ * recorded today with yesterday's `createdAt` is ordinary: it is what importing
16
+ * one, or seeding the default beside applications that already exist, produces. The
17
+ * shared contract writes three out of order and caught it.
18
+ */
19
+ export declare const memoryApplicationStore: (seed?: readonly Application[]) => ApplicationStore;
20
+ //# sourceMappingURL=memory.d.ts.map
@@ -0,0 +1,79 @@
1
+ import { applyPatch } from "../patch.js";
2
+ import { err, ok } from "../result.js";
3
+ import { matchesListing } from "../project/store.js";
4
+ import { applicationSchema } from "./application.js";
5
+ /**
6
+ * A `ApplicationStore` in a `Map`, for a test and for a deployment with no database.
7
+ *
8
+ * The counterpart to `memoryStore`, and it carries the same warning: a `Map`
9
+ * keeps nothing across a process, so on the serverless hosts §3 targets it
10
+ * keeps nothing at all. What it is honestly for is the suite, a lesson, and the
11
+ * first run of an application that has not been given a `DATABASE_URL` yet —
12
+ * where seeing one application called *your application* beats seeing an error.
13
+ *
14
+ * The listing sorts, and the first draft of this file did not — its comment
15
+ * claimed insertion order "happens to be oldest first", which confuses the
16
+ * order rows were *written* with the order they were *created*. An application
17
+ * recorded today with yesterday's `createdAt` is ordinary: it is what importing
18
+ * one, or seeding the default beside applications that already exist, produces. The
19
+ * shared contract writes three out of order and caught it.
20
+ */
21
+ export const memoryApplicationStore = (seed = []) => {
22
+ const applications = new Map(seed.map((application) => [application.applicationId, application]));
23
+ const read = (applicationId) => {
24
+ const found = applications.get(applicationId);
25
+ return found === undefined ? err({ code: "not-found", applicationId }) : ok(found);
26
+ };
27
+ return {
28
+ create: async (application) => {
29
+ if (applications.has(application.applicationId)) {
30
+ return err({ code: "already-exists", applicationId: application.applicationId });
31
+ }
32
+ applications.set(application.applicationId, application);
33
+ return ok(application);
34
+ },
35
+ get: async (applicationId) => read(applicationId),
36
+ list: async (listing) => ok([...applications.values()]
37
+ .filter((application) => matchesListing(application.closedAt, listing))
38
+ .sort((left, right) => left.createdAt.localeCompare(right.createdAt))),
39
+ rename: async (applicationId, to) => {
40
+ const found = read(applicationId);
41
+ if (!found.ok)
42
+ return found;
43
+ /**
44
+ * Parsed rather than spread, so a name this store would accept and the
45
+ * database would refuse cannot be told apart by which one you used. The
46
+ * two stores agree about what an application is because they both ask
47
+ * `applicationSchema`, and they agree about what a patch means because
48
+ * they both apply it with `applyPatch`.
49
+ */
50
+ const next = applicationSchema.safeParse(applyPatch(found.value, to));
51
+ if (!next.success) {
52
+ return err({ code: "unreadable", applicationId, detail: next.error.issues[0]?.message ?? "invalid" });
53
+ }
54
+ applications.set(applicationId, next.data);
55
+ return ok(next.data);
56
+ },
57
+ /** Idempotent, and the instant does not move (0289). */
58
+ close: async (applicationId, at) => {
59
+ const found = read(applicationId);
60
+ if (!found.ok)
61
+ return found;
62
+ if (found.value.closedAt !== undefined)
63
+ return ok(found.value);
64
+ const next = { ...found.value, closedAt: at };
65
+ applications.set(applicationId, next);
66
+ return ok(next);
67
+ },
68
+ reopen: async (applicationId) => {
69
+ const found = read(applicationId);
70
+ if (!found.ok)
71
+ return found;
72
+ /** Spelled as a removal rather than `closedAt: undefined`, which a strict parse refuses. */
73
+ const { closedAt: _was, ...open } = found.value;
74
+ applications.set(applicationId, open);
75
+ return ok(open);
76
+ },
77
+ };
78
+ };
79
+ //# sourceMappingURL=memory.js.map
@@ -0,0 +1,101 @@
1
+ import type { Patch } from "../patch.js";
2
+ import type { Listing } from "../project/store.js";
3
+ import type { Result } from "../result.js";
4
+ import type { Application, ApplicationId } from "./application.js";
5
+ /**
6
+ * Custody of the applications a deployment has.
7
+ *
8
+ * Five tables carry an application's id, so a tree, a hold, a policy revision
9
+ * and a journal entry each know which application they belong to — and for a
10
+ * day nothing stored the application itself. `Application` was a type nothing
11
+ * wrote and `DEFAULT_APPLICATION_ID` was the only one that could be named, so a
12
+ * portal whose first screen lists the applications you have had nothing to
13
+ * list. The maintainer's own sentence — *"the whole portal is geared toward one
14
+ * app when I can have many"* — stayed true of the data after it had stopped
15
+ * being true of the schema.
16
+ *
17
+ * This is the row that makes an application nameable, and it is deliberately
18
+ * thin for the reason `applicationSchema` gives: the registry, the policy and
19
+ * the ingest credential are each already somebody's, so this says only that the
20
+ * application exists, what a person calls it, and which project it is in
21
+ * ([0269](../../decisions/0269-an-application-is-the-unit-loom-governs-and-a-project-groups-them.md)).
22
+ */
23
+ export type ApplicationStoreError =
24
+ /** No application under this id. */
25
+ {
26
+ readonly code: "not-found";
27
+ readonly applicationId: ApplicationId;
28
+ } | {
29
+ readonly code: "already-exists";
30
+ readonly applicationId: ApplicationId;
31
+ }
32
+ /** A row the current code cannot parse, which is a row an older one wrote. */
33
+ | {
34
+ readonly code: "unreadable";
35
+ readonly applicationId: ApplicationId;
36
+ readonly detail: string;
37
+ } | {
38
+ readonly code: "unavailable";
39
+ readonly detail: string;
40
+ };
41
+ export type ApplicationStoreErrorCode = ApplicationStoreError["code"];
42
+ /**
43
+ * The four codes, in the order a deployment meets them, for the same reason
44
+ * `storeErrorCodes` exists: anything that walks the taxonomy rather than
45
+ * reacting to one member otherwise keeps a copy that is silently wrong the day
46
+ * a fifth lands.
47
+ */
48
+ export declare const applicationStoreErrorCodes: readonly ApplicationStoreErrorCode[];
49
+ export declare const describeApplicationStoreError: (error: ApplicationStoreError) => string;
50
+ /**
51
+ * Six methods, and still **no delete**.
52
+ *
53
+ * That is the same refusal `TreeStore` makes and for a stronger reason here: a
54
+ * application's rows are its trees, its revisions, its holds, its policy history
55
+ * and its journal, and a delete would either orphan all of them or cascade
56
+ * through the governance record this product exists to keep. *The application says
57
+ * it was closed* is a better answer than *the application is gone* — and closing is
58
+ * not built here either, because nothing can close what nothing has yet opened.
59
+ * When it is wanted it is a column and a filter, not a `DELETE`.
60
+ */
61
+ export type ApplicationStore = {
62
+ /**
63
+ * Record an application. Refuses an id already taken rather than overwriting,
64
+ * because the thing under that id owns rows.
65
+ */
66
+ readonly create: (application: Application) => Promise<Result<Application, ApplicationStoreError>>;
67
+ /** One application. */
68
+ readonly get: (applicationId: ApplicationId) => Promise<Result<Application, ApplicationStoreError>>;
69
+ /**
70
+ * Every application, oldest first.
71
+ *
72
+ * Unpaginated, and that is a judgement rather than an oversight: this is the
73
+ * list a person scans on one screen, and a deployment whose application count
74
+ * needs a cursor has a different screen's problem. `TreeStore.list` takes a
75
+ * limit because pages are unbounded in a way applications are not.
76
+ */
77
+ readonly list: (listing?: Listing) => Promise<Result<readonly Application[], ApplicationStoreError>>;
78
+ /**
79
+ * Change what a person calls it, and where they say it lives.
80
+ *
81
+ * A field left out is left alone, and `host: null` removes it — the three
82
+ * states `Patch` spells, because an application that has been given a host
83
+ * has to be able to have it taken away. A name has no third state: it is
84
+ * required, so there is nothing for clearing it to mean and the type does not
85
+ * offer it.
86
+ */
87
+ readonly rename: (applicationId: ApplicationId, to: {
88
+ readonly name?: string;
89
+ readonly host?: Patch<string>;
90
+ }) => Promise<Result<Application, ApplicationStoreError>>;
91
+ /**
92
+ * Stop it, without losing it (0289). Closed by its own id, or by its project
93
+ * closing — `ProjectStore.close` does this to every application it holds.
94
+ *
95
+ * Idempotent on one already closed: the instant stays where it was.
96
+ */
97
+ readonly close: (applicationId: ApplicationId, at: string) => Promise<Result<Application, ApplicationStoreError>>;
98
+ /** The inverse, one application at a time. See `ProjectStore.reopen`. */
99
+ readonly reopen: (applicationId: ApplicationId) => Promise<Result<Application, ApplicationStoreError>>;
100
+ };
101
+ //# sourceMappingURL=store.d.ts.map
@@ -0,0 +1,25 @@
1
+ /**
2
+ * The four codes, in the order a deployment meets them, for the same reason
3
+ * `storeErrorCodes` exists: anything that walks the taxonomy rather than
4
+ * reacting to one member otherwise keeps a copy that is silently wrong the day
5
+ * a fifth lands.
6
+ */
7
+ export const applicationStoreErrorCodes = [
8
+ "not-found",
9
+ "already-exists",
10
+ "unreadable",
11
+ "unavailable",
12
+ ];
13
+ export const describeApplicationStoreError = (error) => {
14
+ switch (error.code) {
15
+ case "not-found":
16
+ return `no application ${error.applicationId}`;
17
+ case "already-exists":
18
+ return `application ${error.applicationId} already exists`;
19
+ case "unreadable":
20
+ return `application ${error.applicationId} could not be read: ${error.detail}`;
21
+ case "unavailable":
22
+ return `the application store is unavailable: ${error.detail}`;
23
+ }
24
+ };
25
+ //# sourceMappingURL=store.js.map
@@ -0,0 +1,36 @@
1
+ /**
2
+ * The group of readers a form of a page was served to.
3
+ *
4
+ * An audience is a **predicate over the opaque render context** — site, region,
5
+ * locale, cohort, flag, whatever the host puts in `RenderRequest.context` — and
6
+ * the match is evaluated in the customer's own process, per request, with
7
+ * nothing about the reader leaving it (0263 clauses 1 and 4).
8
+ *
9
+ * **None of that predicate is here.** What this module holds is the *name* a
10
+ * signal carries once the deciding is done: an opaque id, on the terms
11
+ * [0284](../../decisions/0284-a-signal-names-the-audience-it-was-collected-under-and-the-predicate-stays-in-the-control-plane.md)
12
+ * settles. What an `aud_` means is the control plane's to say, exactly as what
13
+ * an `app_` means is — so this file is an identity and a default, which is the
14
+ * whole of what a dimension needs to be measurable.
15
+ */
16
+ import { z } from "zod";
17
+ export declare const audienceIdSchema: z.ZodBranded<z.ZodString, "AudienceId">;
18
+ export type AudienceId = z.infer<typeof audienceIdSchema>;
19
+ /** A new audience's id, minted when somebody defines one. Random, as every other is. */
20
+ export declare const newAudienceId: () => AudienceId;
21
+ /**
22
+ * The audience that matches every reader.
23
+ *
24
+ * What a deployment serving one form of every page has always been doing
25
+ * without having a word for it, which is why it is also what a signal naming
26
+ * no audience is filed under. Rows written before this dimension existed read
27
+ * as this one, and that is true of them rather than a guess (0260): there was
28
+ * one form of every page, so every reader was in the same group.
29
+ *
30
+ * **It is not a null.** Every read filters on it and every write sets it; what
31
+ * makes it the default is only that it is the one a sender gets by saying
32
+ * nothing. A nullable dimension would make every counter read a two-case
33
+ * question, one of whose cases no sender can produce (0284).
34
+ */
35
+ export declare const DEFAULT_AUDIENCE_ID: AudienceId;
36
+ //# sourceMappingURL=audience.d.ts.map
@@ -0,0 +1,41 @@
1
+ /**
2
+ * The group of readers a form of a page was served to.
3
+ *
4
+ * An audience is a **predicate over the opaque render context** — site, region,
5
+ * locale, cohort, flag, whatever the host puts in `RenderRequest.context` — and
6
+ * the match is evaluated in the customer's own process, per request, with
7
+ * nothing about the reader leaving it (0263 clauses 1 and 4).
8
+ *
9
+ * **None of that predicate is here.** What this module holds is the *name* a
10
+ * signal carries once the deciding is done: an opaque id, on the terms
11
+ * [0284](../../decisions/0284-a-signal-names-the-audience-it-was-collected-under-and-the-predicate-stays-in-the-control-plane.md)
12
+ * settles. What an `aud_` means is the control plane's to say, exactly as what
13
+ * an `app_` means is — so this file is an identity and a default, which is the
14
+ * whole of what a dimension needs to be measurable.
15
+ */
16
+ import { z } from "zod";
17
+ import { idPattern } from "../grammar.js";
18
+ import { randomIdBody } from "../ids.js";
19
+ /*
20
+ * `aud`, spelled rather than initialled, for the reason an application id is:
21
+ * it is a value a person reads off a screen and puts into their own rules.
22
+ */
23
+ export const audienceIdSchema = z.string().regex(idPattern("aud")).brand();
24
+ /** A new audience's id, minted when somebody defines one. Random, as every other is. */
25
+ export const newAudienceId = () => audienceIdSchema.parse(`aud_${randomIdBody()}`);
26
+ /**
27
+ * The audience that matches every reader.
28
+ *
29
+ * What a deployment serving one form of every page has always been doing
30
+ * without having a word for it, which is why it is also what a signal naming
31
+ * no audience is filed under. Rows written before this dimension existed read
32
+ * as this one, and that is true of them rather than a guess (0260): there was
33
+ * one form of every page, so every reader was in the same group.
34
+ *
35
+ * **It is not a null.** Every read filters on it and every write sets it; what
36
+ * makes it the default is only that it is the one a sender gets by saying
37
+ * nothing. A nullable dimension would make every counter read a two-case
38
+ * question, one of whose cases no sender can produce (0284).
39
+ */
40
+ export const DEFAULT_AUDIENCE_ID = audienceIdSchema.parse("aud_everyone");
41
+ //# sourceMappingURL=audience.js.map
@@ -117,6 +117,25 @@ describe("the primitive registry", () => {
117
117
  expect(audit.notProbeable, describeRegistryAudit(audit)).toEqual([])
118
118
  })
119
119
 
120
+ /**
121
+ * The audit probes from the empty props bag, which the schema of a primitive
122
+ * requiring anything refuses. That is fine for one that hands its props
123
+ * straight to React and not for one that reads them — \`name.toUpperCase()\`
124
+ * on a prop nobody passed throws, and nothing above can judge a component
125
+ * that was never successfully called.
126
+ *
127
+ * The fix is not to loosen the schema. Hand the audit a props bag it accepts:
128
+ *
129
+ * \`\`\`ts
130
+ * auditRegistry(registry, { props: new Map([["your.primitive", [{ name: "Example" }]]]) })
131
+ * \`\`\`
132
+ */
133
+ it("has no primitives the audit could not configure", () => {
134
+ const audit = auditRegistry(registry)
135
+
136
+ expect(audit.notConfigured, describeRegistryAudit(audit)).toEqual([])
137
+ })
138
+
120
139
  /**
121
140
  * The one that stops a page rather than a portal: a component that throws on a
122
141
  * value its own schema accepts is one a tree the validator *accepted* can take
package/dist/data/plan.js CHANGED
Binary file
@@ -46,6 +46,28 @@ export declare const NO_DATA: NodeData;
46
46
  * is the kind of detail every caller gets right once and then forgets.
47
47
  */
48
48
  export declare const nodeDataOf: (answers: Readonly<Record<string, DataOutcome>>) => NodeData;
49
+ /**
50
+ * One planned request's answer: what a source gave back, or the named reason
51
+ * there is none.
52
+ *
53
+ * Named rather than left as its structure because it is half of a seam a host
54
+ * has to carry, and a loader cannot write `Result<JsonValue, DataUnavailable>`
55
+ * into its own return type without reaching past the entry points it is meant
56
+ * to use.
57
+ */
58
+ export type DataAnswer = Result<JsonValue, DataUnavailable>;
59
+ /**
60
+ * Every answer a resolution was built from, as plain data.
61
+ *
62
+ * Pairs and not a `ReadonlyMap`, because the only reason to publish these is
63
+ * that they travel. `JSON.stringify` turns a `Map` into `{}` and says nothing
64
+ * about it, so a host that serialised one would send an empty object, rebuild a
65
+ * resolution that answers nothing, and get a page of `data-unresolved`
66
+ * diagnostics with no hint that the answers were lost in transit rather than
67
+ * never fetched. An array of pairs is the shape every boundary already carries,
68
+ * and `new Map(answers)` is what `buildDataResolution` takes (0281).
69
+ */
70
+ export type DataAnswers = readonly (readonly [RequestKey, DataAnswer])[];
49
71
  /** What a node's data could not do, in the seam's own vocabulary. */
50
72
  export type NodeDataProblem = {
51
73
  readonly kind: "misdeclared";
@@ -87,5 +109,5 @@ export declare const EMPTY_DATA_RESOLUTION: DataResolution;
87
109
  * the same resolution, which is what makes the failure paths testable without a
88
110
  * fake adapter for each one.
89
111
  */
90
- export declare const buildDataResolution: (plan: DataPlan, answers: ReadonlyMap<RequestKey, Result<JsonValue, DataUnavailable>>) => DataResolution;
112
+ export declare const buildDataResolution: (plan: DataPlan, answers: ReadonlyMap<RequestKey, DataAnswer>) => DataResolution;
91
113
  //# sourceMappingURL=resolution.d.ts.map
@@ -2,7 +2,7 @@ import type { JsonObject } from "../json.js";
2
2
  import type { LoomTree } from "../tree/tree.js";
3
3
  import type { DataRegistry } from "./adapter.js";
4
4
  import { type DataPlan } from "./plan.js";
5
- import { type DataResolution } from "./resolution.js";
5
+ import { type DataAnswers, type DataResolution } from "./resolution.js";
6
6
  /**
7
7
  * The one step in serving a page that does IO.
8
8
  *
@@ -40,7 +40,34 @@ export type ResolveDataOptions = {
40
40
  * against a budget the others had already spent.
41
41
  */
42
42
  export declare const DEFAULT_SOURCE_CEILING_MS = 10000;
43
- export declare const resolveDataPlan: (plan: DataPlan, options: ResolveDataOptions) => Promise<DataResolution>;
43
+ /**
44
+ * A resolution, and the answers it was built from.
45
+ *
46
+ * It *is* a `DataResolution`, so a caller that only renders reads nothing new
47
+ * and changes nothing. The extra field is for the host that fetches in one
48
+ * place and renders in another — the arrangement every React framework pushes a
49
+ * host towards, and the one this package could not serve: a resolution is two
50
+ * closures, and a closure cannot cross from a server component to a client one.
51
+ * The answers can, so the far side rebuilds from them:
52
+ *
53
+ * ```ts
54
+ * // where the fetching happens
55
+ * const { answers } = await resolveTreeData(tree, { registry })
56
+ * // wherever the walk happens, given the same tree
57
+ * const data = buildDataResolution(planTreeData(tree), new Map(answers))
58
+ * ```
59
+ *
60
+ * Re-planning rather than carrying the resolution is what keeps the one thing a
61
+ * caller must not get wrong inside the package: *which requests were asked*.
62
+ * Read off the plan it is a guess, and the obvious guess is wrong — a node whose
63
+ * declaration could not be read at all appears in `plan.problems` and never in
64
+ * `plan.bindings`, so a carrier built from the bindings drops exactly the nodes
65
+ * whose diagnostics matter most (0281).
66
+ */
67
+ export interface ResolvedData extends DataResolution {
68
+ readonly answers: DataAnswers;
69
+ }
70
+ export declare const resolveDataPlan: (plan: DataPlan, options: ResolveDataOptions) => Promise<ResolvedData>;
44
71
  /** Plan and resolve in one step, for the ordinary caller that does both. */
45
- export declare const resolveTreeData: (tree: LoomTree, options: ResolveDataOptions) => Promise<DataResolution>;
72
+ export declare const resolveTreeData: (tree: LoomTree, options: ResolveDataOptions) => Promise<ResolvedData>;
46
73
  //# sourceMappingURL=resolve.d.ts.map