@mostra/conformance 0.0.0-stage → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,381 @@
1
+ /**
2
+ * The conformance harness protocol (D143 item 3): how the kit drives a host under test. A host
3
+ * ships a small shim, a program the kit starts, that speaks JSON-RPC 2.0 over its stdin and
4
+ * stdout (one message per line, as the host protocol does) and answers these methods with its
5
+ * real integration: its own client, its own ports, its own store. Any language can implement it;
6
+ * TypeScript hosts get `serveHarness`, and the Rust reference host shows it in Rust.
7
+ *
8
+ * | Method | What the host does |
9
+ * |---|---|
10
+ * | `harness/initialize` | names itself, the ports it serves and the features it supports |
11
+ * | `harness/start` | starts (spawns or attaches to) its Mostra instance for a home, with its ports |
12
+ * | `harness/call` | sends one host-protocol request through its own client and returns the answer |
13
+ * | `harness/stop` | ends its session (a spawned instance exits) |
14
+ * | `harness/store` | reports what its own store holds: deliveries, mirrors, activations, calls |
15
+ * | `harness/script` | (feature `faults`) answers a port the way the kit asks |
16
+ * | `harness/events` | (feature `events`) reads pages from its own named event stream |
17
+ *
18
+ * Within a revision the protocol changes only additively, like the host protocol (D32).
19
+ */
20
+ import * as z from "zod";
21
+
22
+ /** The harness protocol revisions this kit speaks, newest last. */
23
+ export const HARNESS_REVISIONS: readonly string[] = ["2026-10-21"];
24
+
25
+ /** The harness methods by name. */
26
+ export const HARNESS_METHODS: {
27
+ readonly initialize: "harness/initialize";
28
+ readonly start: "harness/start";
29
+ readonly call: "harness/call";
30
+ readonly stop: "harness/stop";
31
+ readonly store: "harness/store";
32
+ readonly script: "harness/script";
33
+ readonly events: "harness/events";
34
+ } = {
35
+ initialize: "harness/initialize",
36
+ start: "harness/start",
37
+ call: "harness/call",
38
+ stop: "harness/stop",
39
+ store: "harness/store",
40
+ script: "harness/script",
41
+ events: "harness/events",
42
+ };
43
+
44
+ /**
45
+ * What a host can do beyond the required methods: `attach` (`harness/start` with
46
+ * `mode: "attach"`), `faults` (`harness/script`, for reference and test hosts) and `events`
47
+ * (`harness/events`). Unknown features are ignored.
48
+ */
49
+ export type HarnessFeature = "attach" | "faults" | "events" | (string & {});
50
+
51
+ /** `harness/initialize`'s params. */
52
+ export interface InitializeParams {
53
+ /** The harness protocol revision. */
54
+ readonly revision: string;
55
+ /** The kit that drives the host. */
56
+ readonly kit: { readonly name: string; readonly version: string };
57
+ }
58
+
59
+ /** `harness/initialize`'s result. */
60
+ export interface InitializeResult {
61
+ /** The harness protocol revision. */
62
+ readonly revision: string;
63
+ /** The host: its name and version. */
64
+ readonly host: { readonly name: string; readonly version: string };
65
+ /** The ports the host registers in `mostra/initialize`. */
66
+ readonly ports: readonly string[];
67
+ /** The harness features the host supports. */
68
+ readonly features: readonly HarnessFeature[];
69
+ }
70
+
71
+ /** The schema of `InitializeResult`. */
72
+ export const InitializeResult: z.ZodType<InitializeResult> = z.object({
73
+ revision: z.string(),
74
+ host: z.object({ name: z.string(), version: z.string() }),
75
+ ports: z.array(z.string()),
76
+ features: z.array(z.string()),
77
+ });
78
+
79
+ /** `harness/start`'s params. */
80
+ export interface StartParams {
81
+ /** The home the host must use: its own choice in production (HO-08), the kit's in a run. */
82
+ readonly home: string;
83
+ /** Variables the host adds to its instance's environment (test switches, fault points). */
84
+ readonly env: Readonly<Record<string, string>>;
85
+ /** Spawn an instance over stdio (default) or attach to the home's daemon (feature `attach`). */
86
+ readonly mode?: "spawn" | "attach";
87
+ }
88
+
89
+ /** The schema of `StartParams`. */
90
+ export const StartParams: z.ZodType<StartParams> = z.object({
91
+ home: z.string(),
92
+ env: z.record(z.string(), z.string()),
93
+ mode: z.enum(["spawn", "attach"]).exactOptional(),
94
+ });
95
+
96
+ /** `harness/start`'s result: what `mostra/initialize` answered the host. */
97
+ export interface StartResult {
98
+ /** The harness protocol revision. */
99
+ readonly revision: string;
100
+ /** The instance the host's session reached: its home, mode, PID, release and platform. */
101
+ readonly instance: {
102
+ readonly home: string;
103
+ readonly mode: string;
104
+ readonly pid: number;
105
+ readonly version: string;
106
+ readonly platform: string;
107
+ };
108
+ /** The session's warnings, such as an unsupported port. */
109
+ readonly warnings: readonly { readonly code: string }[];
110
+ }
111
+
112
+ /** The schema of `StartResult`. */
113
+ export const StartResult: z.ZodType<StartResult> = z.object({
114
+ revision: z.string(),
115
+ instance: z.object({
116
+ home: z.string(),
117
+ mode: z.string(),
118
+ pid: z.number(),
119
+ version: z.string(),
120
+ platform: z.string(),
121
+ }),
122
+ warnings: z.array(z.looseObject({ code: z.string() })),
123
+ });
124
+
125
+ /** `harness/call`'s params: one host-protocol request. */
126
+ export interface CallParams {
127
+ /** The host-protocol method. */
128
+ readonly method: string;
129
+ /** Its params. */
130
+ readonly params: unknown;
131
+ /** How long the host waits for the answer, in milliseconds. */
132
+ readonly timeoutMs?: number;
133
+ }
134
+
135
+ /** The schema of `CallParams`. */
136
+ export const CallParams: z.ZodType<CallParams> = z.object({
137
+ method: z.string(),
138
+ params: z.unknown(),
139
+ timeoutMs: z.number().exactOptional(),
140
+ });
141
+
142
+ /** An instance's error as the host received it: the JSON-RPC code and the diagnostic. */
143
+ export interface CallError {
144
+ /** The diagnostic code (`MOSTRA_…`). */
145
+ readonly code: number;
146
+ /** The diagnostic as it arrived. */
147
+ readonly data: { readonly code: string; readonly message?: string } & Record<string, unknown>;
148
+ }
149
+
150
+ /** `harness/call`'s result: the answer, or the instance's error as it arrived. */
151
+ export type CallResult = { readonly result: unknown } | { readonly error: CallError };
152
+
153
+ /** The schema of `CallResult`. */
154
+ export const CallResult: z.ZodType<CallResult> = z.union([
155
+ z.object({ error: z.object({ code: z.number(), data: z.looseObject({ code: z.string() }) }) }),
156
+ z.object({ result: z.unknown() }),
157
+ ]) as z.ZodType<CallResult>;
158
+
159
+ /** One delivery the host's submissions port received, as its store records it. */
160
+ export interface StoredDelivery {
161
+ /** The delivery's stable ID (`dlv_…`). */
162
+ readonly deliveryId: string;
163
+ /** The submission it delivers. */
164
+ readonly submissionId: string;
165
+ /** The artifact. */
166
+ readonly artifactId: string;
167
+ /** How many times the port was called with this delivery. */
168
+ readonly calls: number;
169
+ /** How many copies the host's store holds: one for a conformant host (H-03). */
170
+ readonly stored: number;
171
+ /** The attempt numbers it saw, in order. */
172
+ readonly attempts: readonly number[];
173
+ /** `envelope.kind` as received. */
174
+ readonly kind: string;
175
+ /** `results.submission.channel`, `.viewer.kind` and `.viewer.ref`. */
176
+ readonly channel: string;
177
+ /** `results.submission.viewer.kind`. */
178
+ readonly viewerKind: string;
179
+ /** `results.submission.viewer.ref`, when the viewer has one. */
180
+ readonly viewerRef?: string;
181
+ /** The order the host stored it in, from 1. */
182
+ readonly order: number;
183
+ }
184
+
185
+ /** What the host's own store and port handlers saw. */
186
+ export interface StoreResult {
187
+ /** The deliveries the host's store holds, in the order it stored them. */
188
+ readonly deliveries: readonly StoredDelivery[];
189
+ /** Draft mirrors, in arrival order. */
190
+ readonly drafts: readonly {
191
+ readonly artifactId: string;
192
+ readonly viewerId: string;
193
+ readonly revision: string;
194
+ readonly kind: string;
195
+ }[];
196
+ /** `trustedControls.activated` calls, in arrival order. */
197
+ readonly activations: readonly {
198
+ readonly artifactId: string;
199
+ readonly control: string;
200
+ readonly viewId: string;
201
+ }[];
202
+ /**
203
+ * `identity.resolve` calls: the artifact, how the request arrived, the header names, and what
204
+ * the host answered (absent when it failed or never answered). Scenarios judge the session by
205
+ * this answer, so a host may name people however it likes.
206
+ */
207
+ readonly identity: readonly {
208
+ readonly artifactId: string;
209
+ readonly via: string;
210
+ readonly headers: readonly string[];
211
+ readonly answer?: { readonly ref: string; readonly name?: string } | null;
212
+ }[];
213
+ /**
214
+ * `trustedControls.policy` calls, with what the host answered (absent when it failed or never
215
+ * answered). Scenarios judge the view by this answer when they can't script one.
216
+ */
217
+ readonly policies: readonly {
218
+ readonly artifactId: string;
219
+ readonly answer?: {
220
+ readonly submitChannels: readonly string[];
221
+ readonly controls?: readonly string[];
222
+ };
223
+ }[];
224
+ /** `secrets.get` calls. */
225
+ readonly secrets: readonly { readonly artifactId: string; readonly name: string }[];
226
+ }
227
+
228
+ /** The schema of `StoreResult`. */
229
+ export const StoreResult: z.ZodType<StoreResult> = z.object({
230
+ deliveries: z.array(
231
+ z.object({
232
+ deliveryId: z.string(),
233
+ submissionId: z.string(),
234
+ artifactId: z.string(),
235
+ calls: z.number(),
236
+ stored: z.number(),
237
+ attempts: z.array(z.number()),
238
+ kind: z.string(),
239
+ channel: z.string(),
240
+ viewerKind: z.string(),
241
+ viewerRef: z.string().optional(),
242
+ order: z.number(),
243
+ }),
244
+ ),
245
+ drafts: z.array(
246
+ z.object({
247
+ artifactId: z.string(),
248
+ viewerId: z.string(),
249
+ revision: z.string(),
250
+ kind: z.string(),
251
+ }),
252
+ ),
253
+ activations: z.array(
254
+ z.object({ artifactId: z.string(), control: z.string(), viewId: z.string() }),
255
+ ),
256
+ identity: z.array(
257
+ z.object({
258
+ artifactId: z.string(),
259
+ via: z.string(),
260
+ headers: z.array(z.string()),
261
+ answer: z
262
+ .union([z.object({ ref: z.string(), name: z.string().optional() }), z.null()])
263
+ .optional(),
264
+ }),
265
+ ),
266
+ policies: z.array(
267
+ z.object({
268
+ artifactId: z.string(),
269
+ answer: z
270
+ .object({
271
+ submitChannels: z.array(z.string()),
272
+ controls: z.array(z.string()).optional(),
273
+ })
274
+ .optional(),
275
+ }),
276
+ ),
277
+ secrets: z.array(z.object({ artifactId: z.string(), name: z.string() })),
278
+ }) as z.ZodType<StoreResult>;
279
+
280
+ /** How a scripted port answers from now on (feature `faults`). */
281
+ export type ScriptParams =
282
+ | {
283
+ readonly port: "submissions";
284
+ readonly answer: "accept" | "retry" | "undeliverable" | "reject" | "fail" | "hang";
285
+ }
286
+ | {
287
+ readonly port: "trustedControls";
288
+ readonly answer:
289
+ | "fail"
290
+ | "hang"
291
+ | {
292
+ readonly submitChannels: readonly string[];
293
+ readonly controls?: readonly string[];
294
+ };
295
+ }
296
+ | {
297
+ readonly port: "identity";
298
+ /** `headers`: the person named by `x-forwarded-user`, else none. */
299
+ readonly answer:
300
+ | "fail"
301
+ | "hang"
302
+ | "headers"
303
+ | null
304
+ | { readonly ref: string; readonly name?: string };
305
+ }
306
+ | { readonly port: "secrets"; readonly answer: Readonly<Record<string, string>> };
307
+
308
+ /** The schema of `ScriptParams`. */
309
+ export const ScriptParams: z.ZodType<ScriptParams> = z.union([
310
+ z.object({
311
+ port: z.literal("submissions"),
312
+ answer: z.enum(["accept", "retry", "undeliverable", "reject", "fail", "hang"]),
313
+ }),
314
+ z.object({
315
+ port: z.literal("trustedControls"),
316
+ answer: z.union([
317
+ z.literal("fail"),
318
+ z.literal("hang"),
319
+ z.object({
320
+ submitChannels: z.array(z.string()),
321
+ controls: z.array(z.string()).optional(),
322
+ }),
323
+ ]),
324
+ }),
325
+ z.object({
326
+ port: z.literal("identity"),
327
+ answer: z.union([
328
+ z.literal("fail"),
329
+ z.literal("hang"),
330
+ z.literal("headers"),
331
+ z.null(),
332
+ z.object({ ref: z.string(), name: z.string().optional() }),
333
+ ]),
334
+ }),
335
+ z.object({ port: z.literal("secrets"), answer: z.record(z.string(), z.string()) }),
336
+ ]) as z.ZodType<ScriptParams>;
337
+
338
+ /** `harness/events`'s params: read pages from the host's own named stream (feature `events`). */
339
+ export interface EventsParams {
340
+ /** The subscriber name: the stream resumes after what this name acknowledged. */
341
+ readonly name: string;
342
+ /** The events filter. */
343
+ readonly filter: { readonly artifacts?: readonly string[]; readonly types?: readonly string[] };
344
+ /** Stop after this many pages, or when `timeoutMs` passes. */
345
+ readonly pages: number;
346
+ /** How long the host waits for the answer, in milliseconds. */
347
+ readonly timeoutMs: number;
348
+ }
349
+
350
+ /** The schema of `EventsParams`. */
351
+ export const EventsParams: z.ZodType<EventsParams> = z.object({
352
+ name: z.string(),
353
+ filter: z.object({
354
+ artifacts: z.array(z.string()).optional(),
355
+ types: z.array(z.string()).optional(),
356
+ }),
357
+ pages: z.number(),
358
+ timeoutMs: z.number(),
359
+ }) as z.ZodType<EventsParams>;
360
+
361
+ /** `harness/events`'s result: the pages read, every one handled and acknowledged. */
362
+ export interface EventsResult {
363
+ /** The pages read, in cursor order. */
364
+ readonly pages: readonly {
365
+ readonly cursor: string;
366
+ readonly events: readonly ({ readonly cursor: string; readonly type: string } & Record<
367
+ string,
368
+ unknown
369
+ >)[];
370
+ }[];
371
+ }
372
+
373
+ /** The schema of `EventsResult`. */
374
+ export const EventsResult: z.ZodType<EventsResult> = z.object({
375
+ pages: z.array(
376
+ z.object({
377
+ cursor: z.string(),
378
+ events: z.array(z.looseObject({ cursor: z.string(), type: z.string() })),
379
+ }),
380
+ ),
381
+ }) as z.ZodType<EventsResult>;
@@ -0,0 +1,146 @@
1
+ /**
2
+ * The host's side of the harness protocol, for hosts written in TypeScript: `serveHarness` reads
3
+ * the kit's requests on stdin and answers them with the host's implementation, on stdout. A host
4
+ * writes its shim as one small program around its real integration:
5
+ *
6
+ * ```ts
7
+ * serveHarness({
8
+ * initialize: () => ({ host: { name: "my-host", version: "1.0.0" }, ports: ["submissions"], features: [] }),
9
+ * start: (params) => myHost.startMostra(params.home, params.env),
10
+ * call: (method, params) => myHost.mostra.call(method, params),
11
+ * stop: () => myHost.stopMostra(),
12
+ * store: () => myHost.conformanceStore(),
13
+ * });
14
+ * ```
15
+ *
16
+ * Nothing but protocol messages may go to stdout; log to stderr.
17
+ */
18
+ import { createDiagnostic, encodeLine, LineSplitter, RpcError, RpcPeer } from "@mostra/protocol";
19
+ import {
20
+ CallParams,
21
+ type CallResult,
22
+ EventsParams,
23
+ type EventsResult,
24
+ HARNESS_METHODS,
25
+ HARNESS_REVISIONS,
26
+ type InitializeResult,
27
+ ScriptParams,
28
+ StartParams,
29
+ type StartResult,
30
+ type StoreResult,
31
+ } from "./protocol.ts";
32
+
33
+ /** What a TypeScript host implements to be driven by the kit. */
34
+ export interface HarnessImplementation {
35
+ /** Who the host is, the ports it serves and its features. */
36
+ initialize(): Omit<InitializeResult, "revision"> | Promise<Omit<InitializeResult, "revision">>;
37
+ /** Starts (or attaches to) the host's instance for `params.home`, with its real ports. */
38
+ start(params: StartParams): StartResult | Promise<StartResult>;
39
+ /** Sends one host-protocol request through the host's client; throw an `RpcError` for an error answer. */
40
+ call(method: string, params: unknown, timeoutMs?: number): unknown;
41
+ /** Ends the host's session. */
42
+ stop(): void | Promise<void>;
43
+ /** What the host's own store holds. */
44
+ store(): StoreResult | Promise<StoreResult>;
45
+ /** Feature `faults`: answer a port as the kit asks. */
46
+ script?(params: ScriptParams): void | Promise<void>;
47
+ /** Feature `events`: read pages from the host's own named event stream. */
48
+ events?(params: EventsParams): EventsResult | Promise<EventsResult>;
49
+ }
50
+
51
+ function invalid(method: string, message: string): RpcError {
52
+ return new RpcError(
53
+ createDiagnostic("MOSTRA_HOST_INVALID_PARAMS", { message: `${method}: ${message}` }),
54
+ -32602,
55
+ );
56
+ }
57
+
58
+ /**
59
+ * Serves the harness protocol on this process's stdin and stdout until stdin ends, then stops
60
+ * the host's session and resolves.
61
+ */
62
+ export function serveHarness(
63
+ implementation: HarnessImplementation,
64
+ io: { input?: NodeJS.ReadableStream; output?: NodeJS.WritableStream } = {},
65
+ ): Promise<void> {
66
+ const input = io.input ?? process.stdin;
67
+ const output = io.output ?? process.stdout;
68
+ const peer = new RpcPeer({
69
+ send: (message) => {
70
+ output.write(encodeLine(message));
71
+ },
72
+ onRequest: async (method, params) => {
73
+ switch (method) {
74
+ case HARNESS_METHODS.initialize: {
75
+ const revision = HARNESS_REVISIONS.at(-1) as string;
76
+ return { revision, ...(await implementation.initialize()) };
77
+ }
78
+ case HARNESS_METHODS.start: {
79
+ const parsed = StartParams.safeParse(params);
80
+ if (!parsed.success) throw invalid(method, parsed.error.message);
81
+ return await implementation.start(parsed.data);
82
+ }
83
+ case HARNESS_METHODS.call: {
84
+ const parsed = CallParams.safeParse(params);
85
+ if (!parsed.success) throw invalid(method, parsed.error.message);
86
+ try {
87
+ const result = await implementation.call(
88
+ parsed.data.method,
89
+ parsed.data.params,
90
+ parsed.data.timeoutMs,
91
+ );
92
+ return { result: result ?? null } satisfies CallResult;
93
+ } catch (error) {
94
+ if (error instanceof RpcError)
95
+ return {
96
+ error: { code: error.code, data: { ...error.diagnostic } },
97
+ } satisfies CallResult;
98
+ throw error;
99
+ }
100
+ }
101
+ case HARNESS_METHODS.stop:
102
+ await implementation.stop();
103
+ return {};
104
+ case HARNESS_METHODS.store:
105
+ return await implementation.store();
106
+ case HARNESS_METHODS.script: {
107
+ if (!implementation.script) break;
108
+ const parsed = ScriptParams.safeParse(params);
109
+ if (!parsed.success) throw invalid(method, parsed.error.message);
110
+ await implementation.script(parsed.data);
111
+ return {};
112
+ }
113
+ case HARNESS_METHODS.events: {
114
+ if (!implementation.events) break;
115
+ const parsed = EventsParams.safeParse(params);
116
+ if (!parsed.success) throw invalid(method, parsed.error.message);
117
+ return await implementation.events(parsed.data);
118
+ }
119
+ }
120
+ throw new RpcError(
121
+ createDiagnostic("MOSTRA_HOST_METHOD_UNKNOWN", {
122
+ message: `This host serves no harness method ${method}.`,
123
+ }),
124
+ -32601,
125
+ );
126
+ },
127
+ onInternalError: (error, method) => {
128
+ process.stderr.write(`harness: ${method} failed: ${(error as Error).stack ?? error}\n`);
129
+ },
130
+ });
131
+ const lines = new LineSplitter();
132
+ (input as NodeJS.ReadStream).setEncoding?.("utf8");
133
+ input.on("data", (chunk: string) => {
134
+ for (const line of lines.push(chunk)) peer.receiveLine(line);
135
+ });
136
+ return new Promise((done) => {
137
+ input.on("end", () => {
138
+ void Promise.resolve(implementation.stop())
139
+ .catch(() => undefined)
140
+ .finally(() => {
141
+ peer.close();
142
+ done();
143
+ });
144
+ });
145
+ });
146
+ }
package/src/index.ts ADDED
@@ -0,0 +1,65 @@
1
+ /**
2
+ * `@mostra/conformance`: prove a host's Mostra integration (HO-05, D143). The kit runs scenarios
3
+ * (durability across restart, exactly-once delivery, outbox replay, identity, trusted controls,
4
+ * hygiene, version negotiation, long-lived state, the authoring directory's removal and more)
5
+ * against a host through the harness protocol, judges them against the host's expected-failure
6
+ * baseline, and ships reference hosts to copy.
7
+ *
8
+ * ```ts
9
+ * const report = await runConformance({ host: "node my-host-harness.js", baseline });
10
+ * if (!report.ok) process.exitCode = 1;
11
+ * ```
12
+ *
13
+ * @packageDocumentation
14
+ */
15
+ export { type Baseline, NO_BASELINE, readBaseline } from "./baseline.ts";
16
+ export { FIXTURES, type Fixture } from "./fixtures.ts";
17
+ export { codeOf, HostUnderTest, InstanceError } from "./harness/client.ts";
18
+ export {
19
+ type CallError,
20
+ type CallParams,
21
+ type CallResult,
22
+ type EventsParams,
23
+ type EventsResult,
24
+ HARNESS_METHODS,
25
+ HARNESS_REVISIONS,
26
+ type HarnessFeature,
27
+ type InitializeParams,
28
+ type InitializeResult,
29
+ type ScriptParams,
30
+ type StartParams,
31
+ type StartResult,
32
+ type StoredDelivery,
33
+ type StoreResult,
34
+ } from "./harness/protocol.ts";
35
+ export { type HarnessImplementation, serveHarness } from "./harness/serve.ts";
36
+ export { REFERENCE_FAULTS, ReferenceStore, runReferenceHost } from "./reference-host.ts";
37
+ export {
38
+ type ConformanceReport,
39
+ type RunOptions,
40
+ runConformance,
41
+ type ScenarioOutcome,
42
+ type ScenarioStatus,
43
+ } from "./runner.ts";
44
+ export {
45
+ check,
46
+ NotApplicable,
47
+ type RunSettings,
48
+ type Scenario,
49
+ ScenarioContext,
50
+ ScenarioFailure,
51
+ same,
52
+ } from "./scenario.ts";
53
+ export { SCENARIOS } from "./scenarios/index.ts";
54
+ export {
55
+ type Answer,
56
+ type Ask,
57
+ Browser,
58
+ OpenError,
59
+ type ParsedLink,
60
+ parseLink,
61
+ type RunState,
62
+ resultOf,
63
+ send,
64
+ Viewer,
65
+ } from "./viewer.ts";