@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
@@ -0,0 +1,150 @@
1
+ import { describe, expect, it } from "vitest";
2
+ import { everyMemberOf } from "../closed-set.js";
3
+ import { interpretationReplyJsonSchema } from "../interpretation/schema.js";
4
+ import { INSERT_NOTE_REPLY } from "./model-replies.js";
5
+ export const MODEL_SITUATIONS = everyMemberOf()([
6
+ "answers",
7
+ "answers-without-text",
8
+ "truncates",
9
+ "refuses",
10
+ "refuses-the-caller",
11
+ "refuses-the-request",
12
+ "asks-for-later",
13
+ "never-answers",
14
+ ]);
15
+ /**
16
+ * The text this suite sends through, and the model it says served it.
17
+ *
18
+ * **Deliberately dirty, and that is the whole value of it.** A real reply
19
+ * sometimes arrives wrapped in a code fence with whitespace around it, and an
20
+ * adapter is *not* allowed to clean that up: what a malformed answer means is
21
+ * the interpreter's decision and is covered by the interpreter's own tests
22
+ * (0005). An adapter that trims has moved that decision below the seam, where
23
+ * nothing watches it.
24
+ *
25
+ * This was found by breaking it. The first version of this constant was the
26
+ * bare reply, and an adapter mutated to `text.trim().replace(/^```json/, "")`
27
+ * passed all twenty-five cases — because a no-op on clean input is
28
+ * indistinguishable from doing nothing. The fence and the newlines are what
29
+ * make the assertion an assertion.
30
+ *
31
+ * `INSERT_NOTE_REPLY` inside it rather than a lorem string, so an adapter that
32
+ * parses and re-serialises produces valid JSON that still fails the comparison.
33
+ */
34
+ export const CONTRACT_REPLY = `\n\`\`\`json\n${INSERT_NOTE_REPLY}\n\`\`\`\n`;
35
+ export const CONTRACT_SERVED_BY = "a-model-that-served-it";
36
+ /** The request every case sends. Fixed, because none of these turn on its content. */
37
+ export const contractRequest = () => ({
38
+ model: "a-model",
39
+ maxTokens: 16000,
40
+ effort: "high",
41
+ system: "you translate requests into edits",
42
+ userMessage: "add a footer note",
43
+ outputSchema: interpretationReplyJsonSchema(),
44
+ });
45
+ /**
46
+ * Calls the client and reports what came back, including a throw.
47
+ *
48
+ * The throw is caught here rather than left to fail the test by itself, because
49
+ * "this implementation throws" is a *finding* this suite reports in the same
50
+ * vocabulary as a wrong code — and a rejected promise that escaped would
51
+ * otherwise fail whichever assertion ran next, naming the wrong thing.
52
+ */
53
+ const answered = async (client) => {
54
+ try {
55
+ const completion = await client.complete(contractRequest());
56
+ return completion.ok
57
+ ? { ok: true, text: completion.value.text, servedBy: completion.value.servedBy }
58
+ : { ok: false, error: completion.error };
59
+ }
60
+ catch (cause) {
61
+ return { ok: false, threw: cause instanceof Error ? cause.message : String(cause) };
62
+ }
63
+ };
64
+ const EXPECTED = {
65
+ answers: "ok",
66
+ "answers-without-text": "incomplete",
67
+ truncates: "incomplete",
68
+ refuses: "refused",
69
+ "refuses-the-caller": "misconfigured",
70
+ "refuses-the-request": "rejected",
71
+ "asks-for-later": "unavailable",
72
+ "never-answers": "unavailable",
73
+ };
74
+ export const describeModelClientContract = (name, contract) => {
75
+ describe(`${name} — ModelClient contract`, () => {
76
+ /**
77
+ * The invariant with no exceptions and no `not-expressible`: whatever the
78
+ * situation, the caller gets a value. `modelInterpreter` reads a `Result`
79
+ * and has nowhere to catch, so a rejected promise here is an exception on a
80
+ * path with no handler — a page that never finishes rather than a proposal
81
+ * that failed.
82
+ */
83
+ describe("answers rather than throwing, in every situation it has", () => {
84
+ for (const situation of MODEL_SITUATIONS) {
85
+ const make = contract[situation];
86
+ if (make === "not-expressible")
87
+ continue;
88
+ it(`returns a result when the service ${situation}`, async () => {
89
+ const result = await answered(await make());
90
+ expect(result).not.toHaveProperty("threw");
91
+ });
92
+ }
93
+ });
94
+ describe("names who must act", () => {
95
+ for (const situation of MODEL_SITUATIONS) {
96
+ const make = contract[situation];
97
+ if (make === "not-expressible")
98
+ continue;
99
+ it(`reports ${situation} as ${EXPECTED[situation]}`, async () => {
100
+ const result = await answered(await make());
101
+ expect(result.ok ? "ok" : "error" in result ? result.error.code : "threw").toBe(EXPECTED[situation]);
102
+ });
103
+ }
104
+ });
105
+ /**
106
+ * A detail is what an operator reads at three in the morning. An empty one
107
+ * is the difference between "your key is not accepted" and "something went
108
+ * wrong", and nothing above this seam can recover what the service said.
109
+ */
110
+ describe("says what happened, not that something happened", () => {
111
+ for (const situation of MODEL_SITUATIONS) {
112
+ const make = contract[situation];
113
+ if (make === "not-expressible" || EXPECTED[situation] === "ok")
114
+ continue;
115
+ it(`carries a detail for ${situation}`, async () => {
116
+ const result = await answered(await make());
117
+ expect(result.ok === false && "error" in result && result.error.detail.length > 0).toBe(true);
118
+ });
119
+ }
120
+ });
121
+ /**
122
+ * The seam's own line, and the one an adapter is most tempted to cross. The
123
+ * reply is handed up as text so that parsing, validating and deciding what a
124
+ * malformed answer means stay testable without a network (0005). An adapter
125
+ * that trims whitespace, unwraps a code fence or parses and re-serialises has
126
+ * moved one of those decisions below the line, where nothing covers it.
127
+ */
128
+ describe("hands the reply up unchanged", () => {
129
+ const make = contract.answers;
130
+ if (make === "not-expressible") {
131
+ throw new Error("loom: a ModelClient that cannot answer is not a ModelClient — 'answers' may not be not-expressible");
132
+ }
133
+ it("passes the text through byte for byte", async () => {
134
+ const result = await answered(await make());
135
+ expect(result.ok && result.text).toBe(CONTRACT_REPLY);
136
+ });
137
+ /**
138
+ * Which model served the request is provenance, and it is recorded
139
+ * rather than assumed (0005) — a service may answer with something other
140
+ * than what was asked for, and a client that echoed the request's model
141
+ * back would make that invisible exactly when it mattered.
142
+ */
143
+ it("reports the model that served the request, not the one asked for", async () => {
144
+ const result = await answered(await make());
145
+ expect(result.ok && result.servedBy).toBe(CONTRACT_SERVED_BY);
146
+ });
147
+ });
148
+ });
149
+ };
150
+ //# sourceMappingURL=model-contract.js.map
@@ -0,0 +1,26 @@
1
+ import { type PolicyLog, type RecordPolicyRequest } from "../runtime/index.js";
2
+ import { type GatePolicy } from "../runtime/policy.js";
3
+ /**
4
+ * One suite, run against every `PolicyLog`.
5
+ *
6
+ * The same argument as `store-contract.ts` and `journal-contract.ts`: the
7
+ * promises are not in the type. That a policy's revisions are dense and
8
+ * ascending, that recording what is already current appends nothing, that a
9
+ * digest naming two revisions is reported as naming two — a host discovering any
10
+ * of those from a production incident is the seam being offered without the
11
+ * thing that makes it safe to take.
12
+ *
13
+ * The outcome rules themselves live in `recordOutcomeOf`, shared by both
14
+ * implementations, so this suite is checking that a backend *applies* them: that
15
+ * it finds the right head, writes when told to and not when not, and reads back
16
+ * what it wrote.
17
+ */
18
+ export declare const policyNamed: (policyId: string, overrides?: Record<string, unknown>) => GatePolicy;
19
+ /**
20
+ * A recording, with the two fields a caller always has to supply already filled
21
+ * in. `actor` is required by the type and is spelled out in every fixture rather
22
+ * than defaulted somewhere a test could forget it.
23
+ */
24
+ export declare const recordingOf: (policy: GatePolicy, overrides?: Partial<RecordPolicyRequest>) => RecordPolicyRequest;
25
+ export declare const describePolicyLogContract: (name: string, build: () => PolicyLog | Promise<PolicyLog>) => void;
26
+ //# sourceMappingURL=policy-log-contract.d.ts.map
@@ -0,0 +1,344 @@
1
+ import { beforeEach, describe, expect, it } from "vitest";
2
+ import { MAX_POLICY_REVISION_LIMIT, policyFingerprintOf, policyShapeOf, } from "../runtime/index.js";
3
+ import { gatePolicySchema } from "../runtime/policy.js";
4
+ import { FIXED_INSTANT } from "./doubles.js";
5
+ /**
6
+ * One suite, run against every `PolicyLog`.
7
+ *
8
+ * The same argument as `store-contract.ts` and `journal-contract.ts`: the
9
+ * promises are not in the type. That a policy's revisions are dense and
10
+ * ascending, that recording what is already current appends nothing, that a
11
+ * digest naming two revisions is reported as naming two — a host discovering any
12
+ * of those from a production incident is the seam being offered without the
13
+ * thing that makes it safe to take.
14
+ *
15
+ * The outcome rules themselves live in `recordOutcomeOf`, shared by both
16
+ * implementations, so this suite is checking that a backend *applies* them: that
17
+ * it finds the right head, writes when told to and not when not, and reads back
18
+ * what it wrote.
19
+ */
20
+ export const policyNamed = (policyId, overrides = {}) => gatePolicySchema.parse({ policyId, ...overrides });
21
+ /**
22
+ * A recording, with the two fields a caller always has to supply already filled
23
+ * in. `actor` is required by the type and is spelled out in every fixture rather
24
+ * than defaulted somewhere a test could forget it.
25
+ */
26
+ export const recordingOf = (policy, overrides = {}) => ({
27
+ policy,
28
+ actor: "dana@example.com",
29
+ recordedAt: FIXED_INSTANT,
30
+ ...overrides,
31
+ });
32
+ const expectRevision = (result) => {
33
+ expect(result.ok, result.ok ? "" : JSON.stringify(result.error)).toBe(true);
34
+ if (!result.ok)
35
+ throw new Error("unreachable");
36
+ return result.value;
37
+ };
38
+ export const describePolicyLogContract = (name, build) => {
39
+ describe(`${name} — PolicyLog contract`, () => {
40
+ let log;
41
+ beforeEach(async () => {
42
+ log = await build();
43
+ });
44
+ describe("recording", () => {
45
+ it("calls the first recording first, with no change to describe", async () => {
46
+ const recorded = await log.record(recordingOf(policyNamed("house")));
47
+ expect(recorded.ok).toBe(true);
48
+ if (!recorded.ok)
49
+ return;
50
+ expect(recorded.value.outcome).toBe("first");
51
+ expect(recorded.value.revision.revision).toBe(1);
52
+ expect(recorded.value.revision.policyId).toBe("house");
53
+ expect(recorded.value.revision.actor).toBe("dana@example.com");
54
+ });
55
+ it("stamps the fingerprint of the policy it recorded", async () => {
56
+ const policy = policyNamed("house", { minimumConfidence: 0.9 });
57
+ const recorded = await log.record(recordingOf(policy));
58
+ expect(recorded.ok && recorded.value.revision.fingerprint).toBe(policyFingerprintOf(policy));
59
+ });
60
+ it("numbers revisions densely from one", async () => {
61
+ await log.record(recordingOf(policyNamed("house")));
62
+ await log.record(recordingOf(policyNamed("house", { breadthThreshold: 9 })));
63
+ await log.record(recordingOf(policyNamed("house", { breadthThreshold: 10 })));
64
+ const page = await log.revisions("house");
65
+ expect(page.ok && page.value.revisions.map((entry) => entry.revision)).toEqual([1, 2, 3]);
66
+ });
67
+ it("describes an edit as a change, with the revision it replaced", async () => {
68
+ await log.record(recordingOf(policyNamed("house")));
69
+ const recorded = await log.record(recordingOf(policyNamed("house", { minimumConfidence: 0.9 }), { actor: "sam" }));
70
+ expect(recorded.ok).toBe(true);
71
+ if (!recorded.ok || recorded.value.outcome !== "changed") {
72
+ expect.fail(`expected a change, got ${recorded.ok ? recorded.value.outcome : "an error"}`);
73
+ }
74
+ expect(recorded.value.from.revision).toBe(1);
75
+ expect(recorded.value.revision.revision).toBe(2);
76
+ expect(recorded.value.revision.actor).toBe("sam");
77
+ expect(recorded.value.change.direction).toBe("stricter");
78
+ expect(recorded.value.change.fields.map((field) => field.field)).toEqual([
79
+ "minimumConfidence",
80
+ ]);
81
+ });
82
+ /**
83
+ * The property that stops a deployment writing a revision per boot, and the
84
+ * reason the outcome is three-valued rather than a revision.
85
+ */
86
+ it("appends nothing when the head already says this, and hands back the head", async () => {
87
+ const first = await log.record(recordingOf(policyNamed("house")));
88
+ const again = await log.record(recordingOf(policyNamed("house"), { actor: "someone else" }));
89
+ expect(again.ok).toBe(true);
90
+ if (!again.ok)
91
+ return;
92
+ expect(again.value.outcome).toBe("unchanged");
93
+ expect(again.value.revision.revision).toBe(1);
94
+ expect(again.value.revision.actor).toBe("dana@example.com");
95
+ expect(first.ok && first.value.revision.recordedAt).toBe(again.value.revision.recordedAt);
96
+ const page = await log.revisions("house");
97
+ expect(page.ok && page.value.revisions).toHaveLength(1);
98
+ });
99
+ /**
100
+ * Idempotence is against the head and never against history: going back to
101
+ * an earlier policy is a decision somebody made at a time, and a log that
102
+ * swallowed it would lose the revert.
103
+ */
104
+ it("records a return to an earlier policy as its own revision", async () => {
105
+ const open = policyNamed("house");
106
+ await log.record(recordingOf(open));
107
+ await log.record(recordingOf(policyNamed("house", { minimumConfidence: 0.9 })));
108
+ const back = await log.record(recordingOf(open, { actor: "sam" }));
109
+ expect(back.ok && back.value.outcome).toBe("changed");
110
+ expect(back.ok && back.value.revision.revision).toBe(3);
111
+ const page = await log.revisions("house");
112
+ expect(page.ok && page.value.revisions.map((entry) => entry.revision)).toEqual([1, 2, 3]);
113
+ });
114
+ /** A rename is an edit, which is what a host is asked to do (0033). */
115
+ it("records a rename, although the rules are byte for byte the same", async () => {
116
+ await log.record(recordingOf(policyNamed("house", { minimumConfidence: 0.9 })));
117
+ const renamed = await log.record(recordingOf(policyNamed("house-v2", { minimumConfidence: 0.9 })));
118
+ expect(renamed.ok && renamed.value.outcome).toBe("first");
119
+ expect(renamed.ok && renamed.value.revision.revision).toBe(1);
120
+ });
121
+ it("keeps a note when one was given, and omits the key when none was", async () => {
122
+ const noted = await log.record(recordingOf(policyNamed("house"), { note: "after the October incident" }));
123
+ await log.record(recordingOf(policyNamed("house", { breadthThreshold: 9 })));
124
+ expect(noted.ok && noted.value.revision.note).toBe("after the October incident");
125
+ const page = await log.revisions("house");
126
+ expect(page.ok && page.value.revisions[1] && "note" in page.value.revisions[1]).toBe(false);
127
+ });
128
+ it("reads a policy back whole, with every knob it was recorded with", async () => {
129
+ const policy = policyNamed("house", {
130
+ protectedPrimitiveTypes: ["loom.card"],
131
+ interactiveTypes: { "loom.link": { whenProps: ["href"] } },
132
+ removalThresholds: { medium: 4, high: 16 },
133
+ autoApplyCeiling: { developer: "critical" },
134
+ refusalFloor: "high",
135
+ });
136
+ await log.record(recordingOf(policy));
137
+ const head = expectRevision(await log.current("house"));
138
+ expect(head.policy).toEqual(policy);
139
+ });
140
+ });
141
+ describe("recording against an expected revision", () => {
142
+ it("accepts the recording when the head is the one the caller expected", async () => {
143
+ await log.record(recordingOf(policyNamed("house")));
144
+ const next = await log.record(recordingOf(policyNamed("house", { breadthThreshold: 9 }), { expectedRevision: 1 }));
145
+ expect(next.ok && next.value.revision.revision).toBe(2);
146
+ });
147
+ it("accepts zero as the caller saying nothing is recorded yet", async () => {
148
+ const first = await log.record(recordingOf(policyNamed("house"), { expectedRevision: 0 }));
149
+ expect(first.ok && first.value.outcome).toBe("first");
150
+ });
151
+ it("refuses and writes nothing when somebody recorded in between", async () => {
152
+ await log.record(recordingOf(policyNamed("house")));
153
+ await log.record(recordingOf(policyNamed("house", { breadthThreshold: 9 })));
154
+ const stale = await log.record(recordingOf(policyNamed("house", { breadthThreshold: 20 }), { expectedRevision: 1 }));
155
+ expect(stale.ok).toBe(false);
156
+ if (stale.ok)
157
+ return;
158
+ expect(stale.error).toEqual({
159
+ code: "out-of-date",
160
+ policyId: "house",
161
+ expected: 1,
162
+ current: 2,
163
+ });
164
+ const page = await log.revisions("house");
165
+ expect(page.ok && page.value.revisions).toHaveLength(2);
166
+ });
167
+ it("refuses a first recording that expected a head", async () => {
168
+ const stale = await log.record(recordingOf(policyNamed("house"), { expectedRevision: 1 }));
169
+ expect(stale.ok).toBe(false);
170
+ expect(!stale.ok && stale.error.code).toBe("out-of-date");
171
+ });
172
+ });
173
+ describe("reading the head", () => {
174
+ it("says so when nothing was ever recorded under the name", async () => {
175
+ const missing = await log.current("never-written");
176
+ expect(missing.ok).toBe(false);
177
+ expect(!missing.ok && missing.error).toEqual({
178
+ code: "no-such-policy",
179
+ policyId: "never-written",
180
+ });
181
+ });
182
+ it("answers with the newest revision", async () => {
183
+ await log.record(recordingOf(policyNamed("house")));
184
+ await log.record(recordingOf(policyNamed("house", { minimumConfidence: 0.9 })));
185
+ const head = expectRevision(await log.current("house"));
186
+ expect(head.revision).toBe(2);
187
+ expect(head.policy.minimumConfidence).toBe(0.9);
188
+ });
189
+ it("keeps two names apart", async () => {
190
+ await log.record(recordingOf(policyNamed("house")));
191
+ await log.record(recordingOf(policyNamed("tenant-a", { breadthThreshold: 2 })));
192
+ await log.record(recordingOf(policyNamed("tenant-a", { breadthThreshold: 3 })));
193
+ expect(expectRevision(await log.current("house")).revision).toBe(1);
194
+ expect(expectRevision(await log.current("tenant-a")).revision).toBe(2);
195
+ });
196
+ });
197
+ describe("paging a history", () => {
198
+ const twelve = async (target) => {
199
+ await target.record(recordingOf(policyNamed("house")));
200
+ for (let threshold = 9; threshold <= 19; threshold += 1) {
201
+ await target.record(recordingOf(policyNamed("house", { breadthThreshold: threshold })));
202
+ }
203
+ };
204
+ it("says so when nothing was ever recorded under the name", async () => {
205
+ const missing = await log.revisions("never-written");
206
+ expect(!missing.ok && missing.error.code).toBe("no-such-policy");
207
+ });
208
+ it("pages from the oldest end by default", async () => {
209
+ await twelve(log);
210
+ const page = await log.revisions("house", { limit: 5 });
211
+ expect(page.ok && page.value.revisions.map((entry) => entry.revision)).toEqual([
212
+ 1, 2, 3, 4, 5,
213
+ ]);
214
+ expect(page.ok && page.value.older).toBeNull();
215
+ expect(page.ok && page.value.newer).not.toBeNull();
216
+ });
217
+ it("pages from the newest end when asked, and still answers ascending", async () => {
218
+ await twelve(log);
219
+ const page = await log.revisions("house", { direction: "older", limit: 5 });
220
+ expect(page.ok && page.value.revisions.map((entry) => entry.revision)).toEqual([
221
+ 8, 9, 10, 11, 12,
222
+ ]);
223
+ expect(page.ok && page.value.newer).toBeNull();
224
+ expect(page.ok && page.value.older).not.toBeNull();
225
+ });
226
+ it("walks the whole log in either direction, with no gap and no repeat", async () => {
227
+ await twelve(log);
228
+ for (const direction of ["newer", "older"]) {
229
+ const seen = [];
230
+ let cursor;
231
+ for (let page = 0; page < 10; page += 1) {
232
+ const read = await log.revisions("house", {
233
+ direction,
234
+ limit: 5,
235
+ ...(cursor === undefined ? {} : { cursor }),
236
+ });
237
+ expect(read.ok).toBe(true);
238
+ if (!read.ok)
239
+ return;
240
+ seen.push(...read.value.revisions.map((entry) => entry.revision));
241
+ const next = direction === "newer" ? read.value.newer : read.value.older;
242
+ if (next === null)
243
+ break;
244
+ cursor = next;
245
+ }
246
+ expect(seen.slice().sort((left, right) => left - right)).toEqual(Array.from({ length: 12 }, (_, index) => index + 1));
247
+ expect(new Set(seen).size).toBe(12);
248
+ }
249
+ });
250
+ it("honours a limit", async () => {
251
+ await twelve(log);
252
+ const page = await log.revisions("house", { limit: 3 });
253
+ expect(page.ok && page.value.revisions.map((entry) => entry.revision)).toEqual([1, 2, 3]);
254
+ });
255
+ /**
256
+ * The ceiling is weakly observable here and strongly observable in
257
+ * `policy-log.test.ts`, which drives a log past it: a suite that has to run
258
+ * against Postgres cannot afford to record a hundred and one revisions, and
259
+ * a suite that never exceeds the ceiling cannot see it. Both
260
+ * implementations clamp through `clampPolicyRevisionLimit`, which is tested
261
+ * on its own; this holds the call sites to using it at all.
262
+ */
263
+ it("clamps a limit nobody should be able to ask for", async () => {
264
+ await twelve(log);
265
+ const page = await log.revisions("house", { limit: 10_000 });
266
+ expect(page.ok && page.value.revisions.length).toBeLessThanOrEqual(MAX_POLICY_REVISION_LIMIT);
267
+ });
268
+ it("starts from the end the direction begins at when a cursor is nonsense", async () => {
269
+ await twelve(log);
270
+ const page = await log.revisions("house", { cursor: "not-a-position", limit: 3 });
271
+ expect(page.ok && page.value.revisions.map((entry) => entry.revision)).toEqual([1, 2, 3]);
272
+ });
273
+ });
274
+ describe("the fingerprint join", () => {
275
+ it("finds the revision a judgment ran under", async () => {
276
+ const open = policyNamed("house");
277
+ const strict = policyNamed("house", { minimumConfidence: 0.9 });
278
+ await log.record(recordingOf(open));
279
+ await log.record(recordingOf(strict));
280
+ const found = await log.judgedUnder("house", policyFingerprintOf(open));
281
+ expect(found.ok).toBe(true);
282
+ if (!found.ok || found.value.outcome !== "recorded") {
283
+ expect.fail(`expected one match, got ${found.ok ? found.value.outcome : "an error"}`);
284
+ }
285
+ expect(found.value.revision.revision).toBe(1);
286
+ expect(found.value.revision.policy).toEqual(open);
287
+ });
288
+ /**
289
+ * The outcome a single-answer signature would have got wrong. A policy
290
+ * taken to B and back to A has two revisions with one digest — correctly,
291
+ * they are the same rules — and nothing can say which of them a judgment
292
+ * ran under.
293
+ */
294
+ it("refuses to choose when a policy was changed and changed back", async () => {
295
+ const open = policyNamed("house");
296
+ await log.record(recordingOf(open));
297
+ await log.record(recordingOf(policyNamed("house", { minimumConfidence: 0.9 })));
298
+ await log.record(recordingOf(open));
299
+ const found = await log.judgedUnder("house", policyFingerprintOf(open));
300
+ expect(found.ok).toBe(true);
301
+ if (!found.ok || found.value.outcome !== "ambiguous") {
302
+ expect.fail(`expected ambiguity, got ${found.ok ? found.value.outcome : "an error"}`);
303
+ }
304
+ expect(found.value.revisions.map((entry) => entry.revision)).toEqual([1, 3]);
305
+ });
306
+ it("reports a judgment whose policy was never recorded, and says what is held", async () => {
307
+ const recorded = policyNamed("house");
308
+ await log.record(recordingOf(recorded));
309
+ const elsewhere = policyFingerprintOf(policyNamed("house", { breadthThreshold: 99 }));
310
+ const found = await log.judgedUnder("house", elsewhere);
311
+ expect(found.ok).toBe(true);
312
+ if (!found.ok || found.value.outcome !== "unrecorded") {
313
+ expect.fail(`expected unrecorded, got ${found.ok ? found.value.outcome : "an error"}`);
314
+ }
315
+ expect(found.value.fingerprint).toBe(elsewhere);
316
+ expect(found.value.heldShapes).toEqual([
317
+ policyShapeOf(policyFingerprintOf(recorded)),
318
+ ]);
319
+ });
320
+ /**
321
+ * An empty `heldShapes` is the fact that separates *nothing was recorded
322
+ * under this name* from *everything recorded here came from another build*,
323
+ * and it is a reading rather than an error: a judgment that ran under an
324
+ * unlogged policy is exactly the case this field exists to describe.
325
+ */
326
+ it("answers for a name with nothing in it rather than failing", async () => {
327
+ const found = await log.judgedUnder("never-written", "abcdef12:0123456789abcdef");
328
+ expect(found.ok).toBe(true);
329
+ if (!found.ok || found.value.outcome !== "unrecorded") {
330
+ expect.fail("expected unrecorded");
331
+ }
332
+ expect(found.value.heldShapes).toEqual([]);
333
+ });
334
+ it("does not reach into another policy's revisions", async () => {
335
+ const shared = policyNamed("tenant-a", { breadthThreshold: 9 });
336
+ await log.record(recordingOf(policyNamed("house")));
337
+ await log.record(recordingOf(shared));
338
+ const found = await log.judgedUnder("house", policyFingerprintOf(shared));
339
+ expect(found.ok && found.value.outcome).toBe("unrecorded");
340
+ });
341
+ });
342
+ });
343
+ };
344
+ //# sourceMappingURL=policy-log-contract.js.map
@@ -0,0 +1,14 @@
1
+ import { type Project } from "../project/project.js";
2
+ import type { ProjectStore } from "../project/store.js";
3
+ /**
4
+ * One suite, two implementations.
5
+ *
6
+ * `memoryProjectStore` calls itself the reference implementation; this is what
7
+ * makes that claim checkable rather than aspirational, on the same terms
8
+ * `store-contract.ts` and `hold-contract.ts` already set. The alternative —
9
+ * each store asserted against its own expectations — is how two stores that
10
+ * disagree both stay green.
11
+ */
12
+ export declare const projectFixture: (over?: Partial<Project>) => Project;
13
+ export declare const describeProjectStoreContract: (name: string, make: () => Promise<ProjectStore> | ProjectStore) => void;
14
+ //# sourceMappingURL=project-contract.d.ts.map