@mostra/conformance 0.0.0-placeholder → 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.
@@ -0,0 +1,453 @@
1
+ /**
2
+ * The interaction model a host builds on: submission policies, events with durable cursors,
3
+ * signals, waits, artifact state, complete results, idempotent requests and durability across
4
+ * restarts (IN-07 to IN-10, LL-02, H-02, H-03, H-06 to H-10).
5
+ */
6
+ import { FORM, FORM_V2 } from "../fixtures.ts";
7
+ import { codeOf } from "../harness/client.ts";
8
+ import { check, type Scenario, same } from "../scenario.ts";
9
+ import type { Viewer } from "../viewer.ts";
10
+
11
+ /** Answers and submits on whichever channel the view allows. */
12
+ async function answerAndSubmit(viewer: Viewer, fields: Record<string, unknown>) {
13
+ return viewer.answer(
14
+ fields,
15
+ viewer.ticket.submitChannels.includes("artifact") ? "artifact" : "shell",
16
+ );
17
+ }
18
+
19
+ async function code(answer: { json<T>(): T }): Promise<string | undefined> {
20
+ return answer.json<{ code?: string }>().code;
21
+ }
22
+
23
+ /** IN-07, H-02, LL-02: every submission policy, decided by the host at publish. */
24
+ export const policies: Scenario = {
25
+ id: "interaction.policies",
26
+ title:
27
+ "once per artifact answers a second submit with MOSTRA_SUBMIT_ALREADY and the existing submission; once per viewer, epochs and none behave as specified",
28
+ covers: ["HO-05", "IN-07", "LL-02", "H-02"],
29
+ async run(context) {
30
+ await context.start();
31
+ // once, per artifact (the default)
32
+ const once = await context.published(FORM, { policy: { policy: "once" } });
33
+ const first = await context.viewer(once.artifactId);
34
+ const accepted = await answerAndSubmit(first, { name: "Ada" });
35
+ same(accepted.status, 200, "the first submit under once");
36
+ const second = await context.viewer(once.artifactId);
37
+ const conflict = await answerAndSubmit(second, { name: "Grace" });
38
+ check(conflict.status === 409, `a second submit under once answered ${conflict.status}`);
39
+ same(await code(conflict), "MOSTRA_SUBMIT_ALREADY", "a second submit's code");
40
+ same(
41
+ conflict.json<{ submission?: { id: string } }>().submission?.id,
42
+ accepted.json<{ id: string }>().id,
43
+ "the existing submission carried beside the conflict",
44
+ );
45
+ // once, per viewer: each person once.
46
+ const survey = await context.published(FORM, {
47
+ policy: { policy: "once", scope: "per-viewer" },
48
+ });
49
+ for (const ref of ["ada@example.com", "grace@example.com"]) {
50
+ const person = await context.viewer(survey.artifactId, { link: { viewer: { ref } } });
51
+ same((await answerAndSubmit(person, { name: ref })).status, 200, `${ref}'s submit`);
52
+ }
53
+ const again = await context.viewer(survey.artifactId, {
54
+ link: { viewer: { ref: "ada@example.com" } },
55
+ });
56
+ same(
57
+ await code(await answerAndSubmit(again, { name: "again" })),
58
+ "MOSTRA_SUBMIT_ALREADY",
59
+ "a person's second submit",
60
+ );
61
+ // epochs: rounds linked to each other.
62
+ const rounds = await context.published(FORM, { policy: { policy: "epochs" } });
63
+ const person = await context.viewer(rounds.artifactId, { link: { viewer: { ref: "ada" } } });
64
+ const one = (await answerAndSubmit(person, { name: "round 1" })).json<{
65
+ id: string;
66
+ epoch: number;
67
+ }>();
68
+ const written = await person.write({ name: "round 2" }, { baseRevision: "1" });
69
+ const revision = written.json<{ revision: string }>().revision;
70
+ const twoAnswer = await (person.ticket.submitChannels.includes("artifact")
71
+ ? person.submit(revision)
72
+ : person.shellSubmit(revision));
73
+ same(twoAnswer.status, 200, "the second round's submit");
74
+ const two = twoAnswer.json<{ id: string; epoch: number }>();
75
+ same([one.epoch, two.epoch], [1, 2], "the rounds' epochs");
76
+ const results = await context.results(rounds.artifactId, two.id);
77
+ same(results.submission.previous, one.id, "the second round's previous submission");
78
+ // none: no submission at all.
79
+ const board = await context.published(FORM, { policy: { policy: "none" } });
80
+ const viewer = await context.viewer(board.artifactId);
81
+ same(viewer.ticket.policy.policy, "none", "the view's policy");
82
+ same(
83
+ await code(await answerAndSubmit(viewer, { name: "x" })),
84
+ "MOSTRA_SUBMIT_POLICY_NONE",
85
+ "a submit under none",
86
+ );
87
+ const wait = await context.host
88
+ .call("wait", {
89
+ artifact: { artifactId: board.artifactId },
90
+ until: "submitted",
91
+ timeoutMs: 0,
92
+ })
93
+ .then(
94
+ () => undefined,
95
+ (error: unknown) => codeOf(error),
96
+ );
97
+ same(wait, "MOSTRA_SUBMIT_POLICY_NONE", "wait --until submitted under none");
98
+ },
99
+ };
100
+
101
+ /** IN-08, H-09: a named, filtered subscription resumes after what it acknowledged, restarts included. */
102
+ export const subscriptions: Scenario = {
103
+ id: "events.subscription",
104
+ title:
105
+ "A host's named, filtered event stream sees only the types it asked for, in cursor order, and resumes after its acknowledged cursor across an instance restart",
106
+ covers: ["HO-01", "HO-05", "IN-08", "H-09"],
107
+ needs: ["events"],
108
+ async run(context) {
109
+ await context.start();
110
+ const name = "conformance-host";
111
+ const filter = { types: ["submission.created"] };
112
+ // A new name starts now: nothing earlier is read.
113
+ same(
114
+ (await context.host.events({ name, filter, pages: 1, timeoutMs: 500 })).pages.length,
115
+ 0,
116
+ "pages for a new name",
117
+ );
118
+ const submit = async (who: string): Promise<string> => {
119
+ const receipt = await context.published(FORM);
120
+ const viewer = await context.viewer(receipt.artifactId);
121
+ return (await answerAndSubmit(viewer, { name: who })).json<{ id: string }>().id;
122
+ };
123
+ const first = await submit("Ada");
124
+ const read = await context.host.events({ name, filter, pages: 1, timeoutMs: 10_000 });
125
+ const events = read.pages.flatMap((page) => page.events);
126
+ same(
127
+ events.map((event) => event.type),
128
+ ["submission.created"],
129
+ "the filtered stream's events",
130
+ );
131
+ same(
132
+ (events[0]?.["payload"] as { submissionId?: string } | undefined)?.submissionId,
133
+ first,
134
+ "the submission it names",
135
+ );
136
+ await context.restart();
137
+ const second = await submit("Grace");
138
+ const resumed = await context.host.events({ name, filter, pages: 1, timeoutMs: 10_000 });
139
+ const after = resumed.pages.flatMap((page) => page.events);
140
+ same(
141
+ after.map((event) => (event["payload"] as { submissionId?: string }).submissionId),
142
+ [second],
143
+ "the resumed stream: the next submission, no repeat, no gap",
144
+ );
145
+ const cursors = [...events, ...after].map((event) => BigInt(event.cursor));
146
+ check(
147
+ cursors.every((cursor, i) => i === 0 || cursor > (cursors[i - 1] as bigint)),
148
+ "cursors in order",
149
+ );
150
+ },
151
+ };
152
+
153
+ /** IN-09: signals are events; Mostra wakes nobody. */
154
+ export const signals: Scenario = {
155
+ id: "events.signals",
156
+ title:
157
+ "A page's signal and every submit appear as signal.raised events the host filters; Mostra calls no port and wakes nobody for them",
158
+ covers: ["HO-05", "IN-09", "H-09"],
159
+ async run(context) {
160
+ await context.start();
161
+ const receipt = await context.published(FORM);
162
+ const viewer = await context.viewer(receipt.artifactId);
163
+ const before = await context.store();
164
+ same((await viewer.signal("ping", { n: 1 })).status, 200, "a page's signal");
165
+ const raised = await context.events({
166
+ artifacts: [receipt.artifactId],
167
+ types: ["signal.raised"],
168
+ });
169
+ const ping = raised.events.find((event) => event.payload?.["name"] === "ping");
170
+ check(ping, "no signal.raised for the page's signal");
171
+ same(ping.payload["source"], "artifact", "the signal's source");
172
+ same(ping.payload["payload"], { n: 1 }, "the signal's payload");
173
+ const after = await context.store();
174
+ same(after.deliveries.length, before.deliveries.length, "deliveries a signal caused");
175
+ same(after.drafts.length, before.drafts.length, "draft mirrors a signal caused");
176
+ same((await answerAndSubmit(viewer, { name: "Ada" })).status, 200, "the submit");
177
+ const all = await context.events({ artifacts: [receipt.artifactId], types: ["signal.*"] });
178
+ check(
179
+ all.events.some((event) => event.payload?.["name"] === "submit"),
180
+ "a submit raises no signal.raised named submit (D106)",
181
+ );
182
+ },
183
+ };
184
+
185
+ /** IN-10: waits are level- or edge-triggered as specified, and a timeout loses nothing. */
186
+ export const waits: Scenario = {
187
+ id: "interaction.wait",
188
+ title:
189
+ "wait returns still_waiting with a cursor on timeout and loses nothing; signal and state waits are edge-triggered after the cursor; submitted is level-triggered under once",
190
+ covers: ["HO-05", "IN-10"],
191
+ async run(context) {
192
+ await context.start();
193
+ const receipt = await context.published(FORM);
194
+ const artifact = { artifactId: receipt.artifactId };
195
+ const timedOut = await context.host.call<{ status: string; cursor: string }>("wait", {
196
+ artifact,
197
+ until: "signal:ping",
198
+ timeoutMs: 0,
199
+ });
200
+ same(timedOut.status, "still_waiting", "a wait that times out");
201
+ const viewer = await context.viewer(receipt.artifactId);
202
+ await viewer.signal("ping");
203
+ const caught = await context.host.call<{ status: string; cursor: string }>("wait", {
204
+ artifact,
205
+ until: "signal:ping",
206
+ after: timedOut.cursor,
207
+ timeoutMs: 10_000,
208
+ });
209
+ same(caught.status, "satisfied", "a wait after the cursor of a timed-out wait");
210
+ const edge = await context.host.call<{ status: string }>("wait", {
211
+ artifact,
212
+ until: "signal:ping",
213
+ after: caught.cursor,
214
+ timeoutMs: 0,
215
+ });
216
+ same(edge.status, "still_waiting", "the same signal waited for after its own cursor");
217
+ const state = context.host.call<{ status: string }>("wait", {
218
+ artifact,
219
+ until: "state:done",
220
+ after: caught.cursor,
221
+ timeoutMs: 15_000,
222
+ });
223
+ await context.host.call("state/patch", {
224
+ artifact,
225
+ ops: [{ id: "done", value: true }],
226
+ mutationId: "mut_01JB8Z3QF6S7W3N8D5K2C4V9XC",
227
+ as: "host",
228
+ });
229
+ same((await state).status, "satisfied", "a state wait when the host sets the field");
230
+ await answerAndSubmit(viewer, { name: "Ada" });
231
+ const level = await context.host.call<{ status: string; cursor: string }>("wait", {
232
+ artifact,
233
+ until: "submitted",
234
+ timeoutMs: 0,
235
+ });
236
+ same(level.status, "satisfied", "submitted, after the fact, under once (level-triggered)");
237
+ const levelAfter = await context.host.call<{ status: string }>("wait", {
238
+ artifact,
239
+ until: "submitted",
240
+ after: level.cursor,
241
+ timeoutMs: 0,
242
+ });
243
+ same(levelAfter.status, "satisfied", "submitted after a later cursor, under once per artifact");
244
+ },
245
+ };
246
+
247
+ /** LL-02 and D63: artifact state shared by viewers and the host, with conflicts on both sides. */
248
+ export const longLived: Scenario = {
249
+ id: "interaction.long-lived-state",
250
+ title:
251
+ "Under policy none, viewers and the host share artifact state through compare-and-set: an overlapping write is a conflict on either side, and every change is a state.changed event",
252
+ covers: ["HO-05", "LL-02", "IN-07"],
253
+ async run(context) {
254
+ await context.start();
255
+ const receipt = await context.published(FORM, { policy: { policy: "none" } });
256
+ const artifact = { artifactId: receipt.artifactId };
257
+ const hostWrite = await context.host.call<{ revision: string }>("state/patch", {
258
+ artifact,
259
+ ops: [{ id: "count", value: 1 }],
260
+ mutationId: "mut_01JB8Z3QF6S7W3N8D5K2C4V9XD",
261
+ as: "host",
262
+ });
263
+ const viewer = await context.viewer(receipt.artifactId);
264
+ const stale = await viewer.write({ count: 5 }, { scope: "artifact", baseRevision: "0" });
265
+ same(stale.status, 200, "a stale viewer write's status");
266
+ const conflicts = stale.json<{ conflicts: { id: string }[] }>().conflicts;
267
+ same(
268
+ conflicts.map((conflict) => conflict.id),
269
+ ["count"],
270
+ "the viewer's conflicts",
271
+ );
272
+ const fresh = await viewer.write(
273
+ { count: 2 },
274
+ { scope: "artifact", baseRevision: hostWrite.revision },
275
+ );
276
+ const freshRevision = fresh.json<{ revision: string; conflicts: unknown[] }>();
277
+ same(freshRevision.conflicts, [], "a viewer write on the current revision");
278
+ const hostStale = await context.host.call<{ conflicts: { id: string }[] }>("state/patch", {
279
+ artifact,
280
+ ops: [{ id: "count", value: 9 }],
281
+ baseRevision: hostWrite.revision,
282
+ mutationId: "mut_01JB8Z3QF6S7W3N8D5K2C4V9XE",
283
+ as: "host",
284
+ });
285
+ same(
286
+ hostStale.conflicts.map((conflict) => conflict.id),
287
+ ["count"],
288
+ "the host's conflicts on a field a viewer changed",
289
+ );
290
+ const state = await context.host.call<{ fields: Record<string, { value: unknown }> }>(
291
+ "state/get",
292
+ {
293
+ artifact,
294
+ },
295
+ );
296
+ same(state.fields["count"]?.value, 2, "the shared state");
297
+ const changed = await context.events({
298
+ artifacts: [receipt.artifactId],
299
+ types: ["state.changed"],
300
+ });
301
+ same(changed.events.length, 2, "state.changed events (one per applied write)");
302
+ },
303
+ };
304
+
305
+ /** H-06, H-08, H-10: results name exactly what the viewer saw, stale views flagged. */
306
+ export const results: Scenario = {
307
+ id: "interaction.results",
308
+ title:
309
+ "results/get returns the complete submission: metadata, answers with labels, the exact version and view, a stale view flagged with the newer version, and Markdown",
310
+ covers: ["HO-05", "IN-11", "H-06", "H-08", "H-10"],
311
+ async run(context) {
312
+ await context.start();
313
+ const v1 = await context.published(FORM);
314
+ const viewer = await context.viewer(v1.artifactId);
315
+ context.rewrite(v1.dir, FORM_V2);
316
+ const v2 = await context.publish(v1.dir);
317
+ same(v2.version, 2, "the second version's number");
318
+ const submitted = await viewer.answer(
319
+ { name: "Ada", comment: "on the first version" },
320
+ viewer.ticket.submitChannels.includes("artifact") ? "artifact" : "shell",
321
+ { name: "Your name", comment: "Comment" },
322
+ );
323
+ same(submitted.status, 200, "a submit from the older view");
324
+ const read = await context.results(v1.artifactId);
325
+ same(read.artifact.family, "questionnaire", "the artifact's family");
326
+ same(read.artifact.links, [{ rel: "round-of", artifact: "conformance-round-1" }], "its links");
327
+ const submission = read.submission;
328
+ same(
329
+ [submission.versionId, submission.version],
330
+ [v1.versionId, 1],
331
+ "the version the viewer saw",
332
+ );
333
+ same(submission.viewId, viewer.viewId, "the view");
334
+ same(
335
+ [submission.staleView, submission.latestVersion],
336
+ [true, 2],
337
+ "the stale view and the newer version",
338
+ );
339
+ same(read.answers, { name: "Ada", comment: "on the first version" }, "the answers");
340
+ check(
341
+ read.fields.some((field) => field.id === "name" && field.label === "Your name"),
342
+ "the answers' labels",
343
+ );
344
+ const markdown = await context.host.call<{ markdown: string }>("results/get", {
345
+ artifact: { artifactId: v1.artifactId },
346
+ format: "md",
347
+ });
348
+ check(markdown.markdown.includes("Your name"), "the Markdown results name answers by label");
349
+ },
350
+ };
351
+
352
+ /** H-03: request IDs make retries converge; the same ID for another request is refused. */
353
+ export const idempotency: Scenario = {
354
+ id: "interaction.request-ids",
355
+ title:
356
+ "A retried request with the same requestId or mutationId returns the recorded result; the same ID with other parameters is refused",
357
+ covers: ["HO-05", "H-03"],
358
+ async run(context) {
359
+ await context.start();
360
+ const dir = context.author(FORM);
361
+ const first = await context.publish(dir, { requestId: "req-publish-1" });
362
+ const retried = await context.publish(dir, { requestId: "req-publish-1" });
363
+ same(retried, first, "a retried publish's receipt");
364
+ const reused = await context
365
+ .publish(dir, { requestId: "req-publish-1", policy: { policy: "epochs" } })
366
+ .then(
367
+ () => undefined,
368
+ (error: unknown) => codeOf(error),
369
+ );
370
+ same(reused, "MOSTRA_HOST_REQUEST_ID_REUSED", "a request ID reused with other parameters");
371
+ const patch = {
372
+ artifact: { artifactId: first.artifactId },
373
+ ops: [{ id: "count", value: 3 }],
374
+ mutationId: "mut_01JB8Z3QF6S7W3N8D5K2C4V9XF",
375
+ as: "host",
376
+ };
377
+ const once = await context.host.call("state/patch", patch);
378
+ const twice = await context.host.call("state/patch", patch);
379
+ same(twice, once, "a retried state/patch");
380
+ const link = { artifact: { artifactId: first.artifactId }, requestId: "req-link-1" };
381
+ same(
382
+ (await context.host.call<{ url: string }>("view/url", link)).url,
383
+ (await context.host.call<{ url: string }>("view/url", link)).url,
384
+ "a retried view/url",
385
+ );
386
+ },
387
+ };
388
+
389
+ /** Durability: what Mostra acknowledged survives the instance stopping and starting again. */
390
+ export const durability: Scenario = {
391
+ id: "interaction.durability",
392
+ title:
393
+ "Everything acknowledged (versions, drafts, state, submissions, events) survives the instance stopping and starting again",
394
+ covers: ["HO-05", "IN-12", "H-04"],
395
+ async run(context) {
396
+ await context.start();
397
+ const receipt = await context.published(FORM);
398
+ const viewer = await context.viewer(receipt.artifactId);
399
+ await viewer.write({ comment: "a draft only" });
400
+ await context.host.call("state/patch", {
401
+ artifact: { artifactId: receipt.artifactId },
402
+ ops: [{ id: "count", value: 7 }],
403
+ mutationId: "mut_01JB8Z3QF6S7W3N8D5K2C4V9XG",
404
+ as: "host",
405
+ });
406
+ const submitter = await context.viewer(receipt.artifactId, {
407
+ link: { viewer: { ref: "ada" } },
408
+ });
409
+ same((await answerAndSubmit(submitter, { name: "Ada" })).status, 200, "the submit");
410
+ const before = await context.results(receipt.artifactId);
411
+ const eventsBefore = await context.events({ artifacts: [receipt.artifactId] });
412
+ await context.restart();
413
+ const after = await context.results(receipt.artifactId);
414
+ same(
415
+ after.submission.digest,
416
+ before.submission.digest,
417
+ "the submission's digest after a restart",
418
+ );
419
+ const state = await context.host.call<{ fields: Record<string, { value: unknown }> }>(
420
+ "state/get",
421
+ {
422
+ artifact: { artifactId: receipt.artifactId },
423
+ },
424
+ );
425
+ same(state.fields["count"]?.value, 7, "artifact state after a restart");
426
+ const eventsAfter = await context.events({ artifacts: [receipt.artifactId] });
427
+ same(
428
+ eventsAfter.events.slice(0, eventsBefore.events.length).map((event) => event.cursor),
429
+ eventsBefore.events.map((event) => event.cursor),
430
+ "the event log after a restart",
431
+ );
432
+ // The viewer's draft is still the canonical one: the same link continues it.
433
+ const poll = await viewer.poll();
434
+ same(
435
+ poll.json<{ snapshot?: { draft?: { fields?: Record<string, { value: unknown }> } } }>()
436
+ .snapshot?.draft?.fields?.["comment"]?.value,
437
+ "a draft only",
438
+ "the viewer's draft after a restart",
439
+ );
440
+ },
441
+ };
442
+
443
+ /** The interaction scenarios. */
444
+ export const INTERACTION_SCENARIOS: readonly Scenario[] = [
445
+ policies,
446
+ subscriptions,
447
+ signals,
448
+ waits,
449
+ longLived,
450
+ results,
451
+ idempotency,
452
+ durability,
453
+ ];