@mostra/runtime 0.0.0-stage → 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 (115) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +39 -2
  3. package/dist/bin.d.ts +1 -0
  4. package/dist/bin.js +236 -0
  5. package/dist/bin.js.map +1 -0
  6. package/dist/builder/child/main.d.ts +1 -0
  7. package/dist/builder/child/main.js +1408 -0
  8. package/dist/builder/child/main.js.map +1 -0
  9. package/dist/child-xrHmytks.js +49 -0
  10. package/dist/child-xrHmytks.js.map +1 -0
  11. package/dist/deps/child/install.d.ts +1 -0
  12. package/dist/deps/child/install.js +33 -0
  13. package/dist/deps/child/install.js.map +1 -0
  14. package/dist/index.d.ts +221 -0
  15. package/dist/index.d.ts.map +1 -0
  16. package/dist/index.js +3 -0
  17. package/dist/instance-CzBkUyHu.js +15920 -0
  18. package/dist/instance-CzBkUyHu.js.map +1 -0
  19. package/dist/types-NjNy7gXX.js +57 -0
  20. package/dist/types-NjNy7gXX.js.map +1 -0
  21. package/package.json +87 -3
  22. package/src/actions/index.ts +622 -0
  23. package/src/addressing/index.ts +281 -0
  24. package/src/bin.ts +240 -0
  25. package/src/builder/child/dev.ts +383 -0
  26. package/src/builder/child/fields.ts +363 -0
  27. package/src/builder/child/main.ts +47 -0
  28. package/src/builder/child/plugins.ts +195 -0
  29. package/src/builder/child/scan.ts +459 -0
  30. package/src/builder/child/spa.ts +348 -0
  31. package/src/builder/coverage.ts +72 -0
  32. package/src/builder/index.ts +406 -0
  33. package/src/builder/types.ts +180 -0
  34. package/src/deps/child/install.ts +30 -0
  35. package/src/deps/index.ts +918 -0
  36. package/src/deps/installer.ts +321 -0
  37. package/src/deps/lock.ts +82 -0
  38. package/src/deps/scan.ts +266 -0
  39. package/src/deps/specifier.ts +64 -0
  40. package/src/deps/warm.ts +57 -0
  41. package/src/dev/index.ts +518 -0
  42. package/src/faults.ts +65 -0
  43. package/src/gate.ts +55 -0
  44. package/src/gateway/actions.ts +268 -0
  45. package/src/gateway/browser.ts +650 -0
  46. package/src/gateway/capabilities.ts +760 -0
  47. package/src/gateway/controls.ts +91 -0
  48. package/src/gateway/dev.ts +119 -0
  49. package/src/gateway/http.ts +229 -0
  50. package/src/gateway/identity.ts +101 -0
  51. package/src/gateway/index.ts +1299 -0
  52. package/src/gateway/integrity.ts +117 -0
  53. package/src/gateway/listener.ts +217 -0
  54. package/src/gateway/routes.ts +197 -0
  55. package/src/gateway/serve.ts +138 -0
  56. package/src/gc/index.ts +451 -0
  57. package/src/home/acquire.ts +276 -0
  58. package/src/home/index.ts +16 -0
  59. package/src/home/paths.ts +192 -0
  60. package/src/home/platform.ts +34 -0
  61. package/src/home/record.ts +76 -0
  62. package/src/home/settings.ts +113 -0
  63. package/src/index.ts +30 -0
  64. package/src/instance/index.ts +979 -0
  65. package/src/interaction/ephemeral.ts +300 -0
  66. package/src/interaction/events.ts +355 -0
  67. package/src/interaction/fields.ts +392 -0
  68. package/src/interaction/index.ts +1013 -0
  69. package/src/interaction/outbox.ts +493 -0
  70. package/src/interaction/policy.ts +26 -0
  71. package/src/interaction/results.ts +341 -0
  72. package/src/interaction/runs.ts +313 -0
  73. package/src/interaction/signals.ts +120 -0
  74. package/src/interaction/submissions.ts +585 -0
  75. package/src/interaction/subscriptions.ts +258 -0
  76. package/src/interaction/viewers.ts +187 -0
  77. package/src/interaction/wait.ts +201 -0
  78. package/src/ledger/index.ts +442 -0
  79. package/src/ledger/migrations.ts +596 -0
  80. package/src/ledger/requests.ts +105 -0
  81. package/src/ledger/types.ts +28 -0
  82. package/src/live/index.ts +573 -0
  83. package/src/log.ts +316 -0
  84. package/src/processes/child.ts +67 -0
  85. package/src/processes/environment.ts +64 -0
  86. package/src/processes/identity.ts +191 -0
  87. package/src/processes/index.ts +19 -0
  88. package/src/processes/manager.ts +543 -0
  89. package/src/protocol-server/client.ts +94 -0
  90. package/src/protocol-server/index.ts +91 -0
  91. package/src/protocol-server/server.ts +518 -0
  92. package/src/protocol-server/streams.ts +81 -0
  93. package/src/publish/checks.ts +92 -0
  94. package/src/publish/digest.ts +87 -0
  95. package/src/publish/index.ts +23 -0
  96. package/src/publish/manifest.ts +409 -0
  97. package/src/publish/methods.ts +96 -0
  98. package/src/publish/publisher.ts +913 -0
  99. package/src/publish/source.ts +272 -0
  100. package/src/publish/tar.ts +110 -0
  101. package/src/registry/index.ts +481 -0
  102. package/src/registry/store.ts +136 -0
  103. package/src/secrets/index.ts +223 -0
  104. package/src/service/idle.ts +64 -0
  105. package/src/service/index.ts +3 -0
  106. package/src/service/unit.ts +250 -0
  107. package/src/verify/fields.ts +125 -0
  108. package/src/verify/index.ts +913 -0
  109. package/src/verify/regression.ts +157 -0
  110. package/src/verify/runner.ts +230 -0
  111. package/src/verify/sandbox.ts +407 -0
  112. package/src/verify/typecheck.ts +371 -0
  113. package/src/workers/index.ts +17 -0
  114. package/src/workers/launcher.ts +260 -0
  115. package/src/workers/pool.ts +708 -0
@@ -0,0 +1,913 @@
1
+ /**
2
+ * `verify` (D29, D41, D55, D72, D138; ARCHITECTURE §12, INTERFACES §13): one run over a prepared
3
+ * source, giving one verdict. The stages, in order:
4
+ *
5
+ * 1. **compile**: the build (into `cache/builds/<versionId>/`, which publish promotes) and the type
6
+ * check beside it, inside the build's 180 s. A source that didn't build stops here.
7
+ * 2. **lint**: the static field-ID scan.
8
+ * 3. **boot**: a sandbox (`sandbox.ts`) serving the build and the last passing version.
9
+ * 4. **render**: each viewport of the baseline, then of the source, in the warm browser; a second
10
+ * boot for changing field IDs; the smoke test. 120 s cover stages 3 to 5 (FAILURE_MODEL §9).
11
+ * 5. **regression**: contracts, ARIA and pixels against the baseline.
12
+ *
13
+ * The verdict is cached by source digest, environment digest and {@link VERIFY_REVISION}, unless an
14
+ * error says the run couldn't vouch for the page (the environment, a timeout, a crash): publish
15
+ * reuses it for the same digests (D41).
16
+ */
17
+ import { createHash, randomUUID } from "node:crypto";
18
+ import { existsSync, readFileSync } from "node:fs";
19
+ import { mkdir, readdir, rename, rm, stat, utimes, writeFile } from "node:fs/promises";
20
+ import { join } from "node:path";
21
+ import {
22
+ type ArtifactManifest,
23
+ ariaSummary,
24
+ createDiagnostic,
25
+ type Diagnostic,
26
+ estimateImageTokens,
27
+ type ProbedField,
28
+ type RenderRequest,
29
+ type RenderResult,
30
+ RpcError,
31
+ type ScreenshotPolicy,
32
+ type VerdictAria,
33
+ type VerdictScreenshot,
34
+ VerifyVerdict,
35
+ type VerifyViewport,
36
+ viewportsFor,
37
+ } from "@mostra/protocol";
38
+ import type { VersionRegistry } from "../builder/index.ts";
39
+ import type { Ledger } from "../ledger/index.ts";
40
+ import type { Log, Redactor } from "../log.ts";
41
+ import type { Registry } from "../registry/index.ts";
42
+ import { probedFieldLint, staticFieldLint, unstableFieldLint } from "./fields.ts";
43
+ import { ariaRegression, contractRegressions, pixelRegression } from "./regression.ts";
44
+ import type { RunnerClient } from "./runner.ts";
45
+ import {
46
+ recoverSandboxes,
47
+ type Sandbox,
48
+ type SandboxOptions,
49
+ type SandboxVersion,
50
+ sandboxRoot,
51
+ startSandbox,
52
+ } from "./sandbox.ts";
53
+ import { reportedByBuild, TYPECHECK_REVISION, typecheck } from "./typecheck.ts";
54
+
55
+ export { createRunnerClient, locateRunner, type RunnerClient } from "./runner.ts";
56
+ export {
57
+ type Sandbox,
58
+ type SandboxOptions,
59
+ startSandbox,
60
+ } from "./sandbox.ts";
61
+
62
+ /** The revision of verify's rules: a cached verdict made under other rules is never reused. */
63
+ export const VERIFY_REVISION: string = createHash("sha256")
64
+ .update(`verify 2 ${TYPECHECK_REVISION}`)
65
+ .digest("hex")
66
+ .slice(0, 16);
67
+
68
+ /** How long the stages after compile may take (FAILURE_MODEL §9, D138 item 6). */
69
+ export const VERIFY_TIMEOUT_MS = 120_000;
70
+ /** The smoke test's budget (ROUND-3 §9). */
71
+ export const SMOKE_BUDGET = { maxInteractions: 200, maxMs: 60_000 } as const;
72
+ /** The build cache's cap (D47): least recently used builds go first. */
73
+ const BUILD_CACHE_BYTES = 5 * 1024 ** 3;
74
+ /** How many verdicts the cache keeps. */
75
+ const VERDICT_CACHE_ENTRIES = 200;
76
+
77
+ /** Codes that say a run couldn't vouch for the page: its verdict is never cached (D138 item 5). */
78
+ const UNCACHEABLE =
79
+ /^MOSTRA_(ENV|VERIFY_TIMEOUT|VERIFY_CRASHED|BUILD_TIMEOUT|BUILD_CRASHED|DEP_OFFLINE|DEP_TIMEOUT)/;
80
+
81
+ /** A source prepared for verify or publish: snapshot, manifest, dependencies and digests. */
82
+ export interface PreparedSource {
83
+ /** The source path as the caller named it. */
84
+ readonly path: string;
85
+ /** The staging directory; the snapshot is in its `source/`. */
86
+ readonly stagingDir: string;
87
+ /** The artifact's source directory, where server code runs. */
88
+ readonly sourceDir: string;
89
+ readonly manifest: ArtifactManifest;
90
+ /** The manifest's warnings (unknown keys). */
91
+ readonly warnings: readonly Diagnostic[];
92
+ /** The artifact: known (a manifest `id` or a binding) or provisional. */
93
+ readonly artifactId: string;
94
+ readonly identityKnown: boolean;
95
+ readonly sourceDigest: string;
96
+ readonly envDigest: string;
97
+ readonly versionId: string;
98
+ /** The `node_modules` the build links (D95). */
99
+ readonly nodeModules: string;
100
+ }
101
+
102
+ /** A finished build in a directory, as publish lays out a version. */
103
+ export type BuildOutcome =
104
+ | { readonly ok: true; readonly outputDigest: string; readonly registry: VersionRegistry }
105
+ | { readonly ok: false; readonly diagnostics: readonly Diagnostic[] };
106
+
107
+ /** Options for {@link createVerifier}. */
108
+ export interface VerifierOptions {
109
+ readonly home: string;
110
+ readonly ledger: Ledger;
111
+ readonly registry: Registry;
112
+ readonly log: Log;
113
+ readonly redactor: Redactor;
114
+ readonly runner: RunnerClient;
115
+ readonly sandbox: SandboxOptions;
116
+ /** Clears the artifact's parked worker in the instance's pool (D133). */
117
+ readonly clearPark: (artifactId: string) => void;
118
+ /** Tests shorten the 120 s and the smoke test's 200 interactions. */
119
+ readonly limits?: { readonly timeoutMs?: number; readonly smokeInteractions?: number };
120
+ }
121
+
122
+ /** One run's options. */
123
+ export interface VerifyRun {
124
+ /** Builds the prepared source into `outDir`, laid out as a version (manifest, registry, lock). */
125
+ readonly build: (outDir: string) => Promise<BuildOutcome>;
126
+ readonly screenshots?: ScreenshotPolicy;
127
+ /** Told as each stage starts. */
128
+ readonly progress?: (stage: string) => void;
129
+ }
130
+
131
+ /** What a run found: its verdict, and whether compile produced a build (D138 item 7). */
132
+ export interface VerifyOutcome {
133
+ readonly verdict: VerifyVerdict;
134
+ /**
135
+ * Whether the source built. `--force` never publishes a source that didn't, whatever codes its
136
+ * verdict carries (Opus review finding 7).
137
+ */
138
+ readonly built: boolean;
139
+ }
140
+
141
+ /** The verifier of one instance. */
142
+ export interface Verifier {
143
+ /** Runs verify; replaces the cached verdict for the same digests. */
144
+ run(prepared: PreparedSource, run: VerifyRun): Promise<VerifyOutcome>;
145
+ /** The cached verdict for these digests, if one was made for this artifact (or none named). */
146
+ cached(prepared: PreparedSource): VerifyOutcome | undefined;
147
+ /** Verify's build of a version, when the cache still holds it complete. */
148
+ builtVersion(versionId: string): string | undefined;
149
+ /** `cache/verify/`: the verdicts, and each verdict's screenshots, ARIA snapshots and diffs. */
150
+ readonly cacheDir: string;
151
+ /**
152
+ * gc's part (D140 item 14): verify's builds past the 5 GB cap, oldest first, and screenshot
153
+ * directories no cached verdict names. A dry run lists them; a real run removes them. The
154
+ * caller holds the instance's gate alone, so no verify run serves a build meanwhile.
155
+ */
156
+ collect(dryRun: boolean): Promise<{ readonly count: number; readonly bytes: number }>;
157
+ }
158
+
159
+ /** The source's page never got ready: the browser stages after its first render can't run. */
160
+ class NotReady extends Error {}
161
+
162
+ /** The verdict cache's key for two digests. */
163
+ export function verdictKey(sourceDigest: string, envDigest: string): string {
164
+ return createHash("sha256")
165
+ .update(`${sourceDigest}\u0000${envDigest}\u0000${VERIFY_REVISION}`)
166
+ .digest("hex");
167
+ }
168
+
169
+ const hasError = (diagnostics: readonly Diagnostic[]): boolean =>
170
+ diagnostics.some((diagnostic) => diagnostic.severity === "error");
171
+
172
+ /** The directory size, for the build cache's cap. */
173
+ async function sizeOf(dir: string): Promise<number> {
174
+ let total = 0;
175
+ for (const entry of await readdir(dir, { withFileTypes: true }).catch(() => [])) {
176
+ const path = join(dir, entry.name);
177
+ if (entry.isDirectory()) total += await sizeOf(path);
178
+ else total += (await stat(path).catch(() => ({ size: 0 }))).size;
179
+ }
180
+ return total;
181
+ }
182
+
183
+ /**
184
+ * Removes what a stopped instance left of verify (D138 item 1): sandboxes, builds cut off before
185
+ * they were complete, verdicts' temporary files and the screenshot directories no verdict names
186
+ * (Opus review finding 9). Call it before any run starts.
187
+ */
188
+ export async function recoverVerify(home: string, log: Log): Promise<void> {
189
+ await recoverSandboxes(home, log);
190
+ const buildsDir = join(home, "cache", "builds");
191
+ for (const name of await readdir(buildsDir).catch(() => [] as string[])) {
192
+ if (name.includes(".tmp-")) await rm(join(buildsDir, name), { recursive: true, force: true });
193
+ }
194
+ const cacheDir = join(home, "cache", "verify");
195
+ const entries = await readdir(cacheDir, { withFileTypes: true }).catch(() => []);
196
+ const verdicts = new Set(
197
+ entries.filter((entry) => entry.name.endsWith(".json")).map((entry) => entry.name.slice(0, -5)),
198
+ );
199
+ for (const entry of entries) {
200
+ const path = join(cacheDir, entry.name);
201
+ if (entry.name.endsWith(".tmp")) await rm(path, { force: true });
202
+ else if (entry.isDirectory() && path !== sandboxRoot(home) && !verdicts.has(entry.name))
203
+ await rm(path, { recursive: true, force: true });
204
+ }
205
+ }
206
+
207
+ /** Creates the verifier. */
208
+ export function createVerifier(options: VerifierOptions): Verifier {
209
+ const { home, log, registry } = options;
210
+ const buildsDir = join(home, "cache", "builds");
211
+ const cacheDir = join(home, "cache", "verify");
212
+ /** Builds a run is serving from its sandbox: the cap never removes them (finding 9). */
213
+ const inUse = new Map<string, number>();
214
+ const completeBuild = (versionId: string): string | undefined => {
215
+ const dir = join(buildsDir, versionId);
216
+ return existsSync(join(dir, "manifest.json")) ? dir : undefined;
217
+ };
218
+
219
+ /** Keeps the build cache under its cap, oldest first, never `keep`. */
220
+ const pruneBuilds = async (keep: string): Promise<void> => {
221
+ const entries = await readdir(buildsDir, { withFileTypes: true }).catch(() => []);
222
+ const builds = await Promise.all(
223
+ entries
224
+ .filter((entry) => entry.isDirectory() && !entry.name.includes(".tmp-"))
225
+ .map(async (entry) => {
226
+ const dir = join(buildsDir, entry.name);
227
+ return {
228
+ dir,
229
+ name: entry.name,
230
+ mtime: (await stat(dir)).mtimeMs,
231
+ size: await sizeOf(dir),
232
+ };
233
+ }),
234
+ );
235
+ let total = builds.reduce((acc, build) => acc + build.size, 0);
236
+ for (const build of builds.sort((a, b) => a.mtime - b.mtime)) {
237
+ if (total <= BUILD_CACHE_BYTES) break;
238
+ if (build.name === keep || (inUse.get(build.name) ?? 0) > 0) continue;
239
+ await rm(build.dir, { recursive: true, force: true });
240
+ total -= build.size;
241
+ }
242
+ };
243
+
244
+ /**
245
+ * Keeps the newest verdicts, and removes screenshot directories no verdict names (an uncached
246
+ * run's) once they are an hour old and no run is writing them (finding 9).
247
+ */
248
+ const pruneVerdicts = async (): Promise<void> => {
249
+ const all = await readdir(cacheDir, { withFileTypes: true }).catch(() => []);
250
+ const verdicts = new Set(
251
+ all.filter((entry) => entry.name.endsWith(".json")).map((entry) => entry.name.slice(0, -5)),
252
+ );
253
+ for (const entry of all) {
254
+ if (!entry.isDirectory() || verdicts.has(entry.name) || running.has(entry.name)) continue;
255
+ const path = join(cacheDir, entry.name);
256
+ if (path === sandboxRoot(home)) continue;
257
+ const age = Date.now() - ((await stat(path).catch(() => undefined))?.mtimeMs ?? Date.now());
258
+ if (age > 60 * 60 * 1000) await rm(path, { recursive: true, force: true });
259
+ }
260
+ const names = [...verdicts].map((name) => `${name}.json`);
261
+ if (names.length <= VERDICT_CACHE_ENTRIES) return;
262
+ const dated = await Promise.all(
263
+ names.map(async (name) => ({ name, mtime: (await stat(join(cacheDir, name))).mtimeMs })),
264
+ );
265
+ for (const { name } of dated
266
+ .sort((a, b) => a.mtime - b.mtime)
267
+ .slice(0, names.length - VERDICT_CACHE_ENTRIES)) {
268
+ await rm(join(cacheDir, name), { force: true });
269
+ await rm(join(cacheDir, name.slice(0, -".json".length)), { recursive: true, force: true });
270
+ }
271
+ };
272
+
273
+ /** The newest version of the artifact whose recorded verdict passed (D138 item 4). */
274
+ const baselineOf = (
275
+ artifactId: string,
276
+ ):
277
+ | { readonly versionId: string; readonly dir: string }
278
+ | { readonly missing: string }
279
+ | undefined => {
280
+ const passed = registry.passedVersion(artifactId);
281
+ if (passed === undefined) return undefined;
282
+ const dir = registry.store.versionDir(passed);
283
+ return existsSync(join(dir, "manifest.json")) && existsSync(join(dir, "registry.json"))
284
+ ? { versionId: passed, dir }
285
+ : { missing: passed };
286
+ };
287
+
288
+ /** The answers the home holds under a field ID of an artifact (orphans to be, D42). */
289
+ const savedAnswers = (artifactId: string, fieldId: string): number =>
290
+ options.ledger.read(
291
+ (db) =>
292
+ db.get<{ count: number }>(
293
+ "SELECT COUNT(*) AS count FROM field JOIN document ON document.id = field.document_id WHERE document.artifact_id = ? AND field.field_id = ? AND field.deleted = 0",
294
+ artifactId,
295
+ fieldId,
296
+ )?.count ?? 0,
297
+ );
298
+
299
+ const readRegistry = (dir: string): VersionRegistry =>
300
+ JSON.parse(readFileSync(join(dir, "registry.json"), "utf8")) as VersionRegistry;
301
+
302
+ const sandboxVersion = (versionId: string, dir: string): SandboxVersion => {
303
+ const manifest = JSON.parse(readFileSync(join(dir, "manifest.json"), "utf8")) as {
304
+ manifest: ArtifactManifest;
305
+ sourceDigest: string;
306
+ envDigest: string;
307
+ outputDigest: string;
308
+ };
309
+ return {
310
+ versionId,
311
+ dir,
312
+ manifest: manifest.manifest,
313
+ sourceDigest: manifest.sourceDigest,
314
+ envDigest: manifest.envDigest,
315
+ outputDigest: manifest.outputDigest,
316
+ };
317
+ };
318
+
319
+ /** Builds the source into the build cache (atomically), or reuses a complete build. */
320
+ const buildInto = async (prepared: PreparedSource, run: VerifyRun): Promise<BuildOutcome> => {
321
+ const existing = completeBuild(prepared.versionId);
322
+ if (existing && (await options.sandbox.damage(existing)) === undefined) {
323
+ // Used again: newest for the cap, which goes by the time a build was last used.
324
+ const now = new Date();
325
+ await utimes(existing, now, now).catch(() => undefined);
326
+ return {
327
+ ok: true,
328
+ outputDigest: (
329
+ JSON.parse(readFileSync(join(existing, "manifest.json"), "utf8")) as {
330
+ outputDigest: string;
331
+ }
332
+ ).outputDigest,
333
+ registry: readRegistry(existing),
334
+ };
335
+ }
336
+ await mkdir(buildsDir, { recursive: true, mode: 0o700 });
337
+ const temporary = join(buildsDir, `${prepared.versionId}.tmp-${process.pid}-${Date.now()}`);
338
+ try {
339
+ const outcome = await run.build(temporary);
340
+ if (!outcome.ok) return outcome;
341
+ await rm(join(buildsDir, prepared.versionId), { recursive: true, force: true });
342
+ await rename(temporary, join(buildsDir, prepared.versionId));
343
+ await pruneBuilds(prepared.versionId);
344
+ return outcome;
345
+ } finally {
346
+ await rm(temporary, { recursive: true, force: true });
347
+ }
348
+ };
349
+
350
+ const verify = async (prepared: PreparedSource, run: VerifyRun): Promise<VerifyOutcome> => {
351
+ inUse.set(prepared.versionId, (inUse.get(prepared.versionId) ?? 0) + 1);
352
+ try {
353
+ return await verifyInUse(prepared, run);
354
+ } finally {
355
+ const count = (inUse.get(prepared.versionId) ?? 1) - 1;
356
+ if (count > 0) inUse.set(prepared.versionId, count);
357
+ else inUse.delete(prepared.versionId);
358
+ }
359
+ };
360
+
361
+ const verifyInUse = async (prepared: PreparedSource, run: VerifyRun): Promise<VerifyOutcome> => {
362
+ const started = Date.now();
363
+ const timings: Record<string, number> = {};
364
+ const time = (stage: string, since: number): void => {
365
+ timings[stage] = Date.now() - since;
366
+ };
367
+ const diagnostics: Diagnostic[] = [...prepared.warnings];
368
+ const key = verdictKey(prepared.sourceDigest, prepared.envDigest);
369
+ const artifactsDir = join(cacheDir, key);
370
+ await rm(artifactsDir, { recursive: true, force: true });
371
+ await mkdir(artifactsDir, { recursive: true, mode: 0o700 });
372
+ const { viewports, unknown } = viewportsFor(prepared.manifest.verify?.viewports);
373
+ if (unknown.length > 0) log.warn("verify.unknown_viewports", { unknown });
374
+
375
+ // 1. Compile: the build and the type check beside it.
376
+ run.progress?.("compile");
377
+ const compileStart = Date.now();
378
+ const hasLive = existsSync(join(prepared.stagingDir, "source", "live.ts"));
379
+ let buildDiagnostics: readonly Diagnostic[] = [];
380
+ const [built, checked] = await Promise.all([
381
+ buildInto(prepared, run).then((outcome) => {
382
+ time("build", compileStart);
383
+ if (!outcome.ok) buildDiagnostics = outcome.diagnostics;
384
+ return outcome;
385
+ }),
386
+ typecheck({
387
+ processes: options.sandbox.processes,
388
+ log,
389
+ env: options.sandbox.env,
390
+ sourceDir: join(prepared.stagingDir, "source"),
391
+ workDir: `${prepared.stagingDir}-check`,
392
+ nodeModules: prepared.nodeModules,
393
+ hasLive,
394
+ alreadyReported: (specifier) => reportedByBuild(buildDiagnostics, specifier),
395
+ }).then((outcome) => {
396
+ time("typecheck", compileStart);
397
+ return outcome;
398
+ }),
399
+ ]);
400
+ diagnostics.push(...(built.ok ? [] : built.diagnostics));
401
+ // A module the build already couldn't resolve isn't reported twice (D138 item 8). The type
402
+ // check's own callback may run before the build ends, so its TS2307s are matched again here.
403
+ diagnostics.push(
404
+ ...checked.diagnostics.filter((diagnostic) => {
405
+ if (built.ok || diagnostic.code !== "MOSTRA_TYPE_ERROR") return true;
406
+ const missing = /^TS2307: .*?'([^']+)'/.exec(diagnostic.message)?.[1];
407
+ return missing === undefined || !reportedByBuild(built.diagnostics, missing);
408
+ }),
409
+ );
410
+
411
+ const regressions: {
412
+ against?: string;
413
+ aria?: string;
414
+ pixels?: { viewport: string; ratio: number }[];
415
+ contracts?: string[];
416
+ } = {};
417
+ const screenshots: VerdictScreenshot[] = [];
418
+ const aria: VerdictAria[] = [];
419
+ const smoke = { interactions: 0, skippedActions: [] as string[], stateChanges: 0 };
420
+
421
+ if (built.ok) {
422
+ // 2. Lint: the static field-ID scan.
423
+ const lintStart = Date.now();
424
+ const coverage = built.registry.fields;
425
+ diagnostics.push(...staticFieldLint(coverage));
426
+ time("lint", lintStart);
427
+
428
+ const baseline = prepared.identityKnown ? baselineOf(prepared.artifactId) : undefined;
429
+ if (!baseline) {
430
+ diagnostics.push(
431
+ createDiagnostic("MOSTRA_VERIFY_NO_BASELINE", {
432
+ message: "No earlier version of this artifact passed verify, so nothing was compared.",
433
+ }),
434
+ );
435
+ } else if ("missing" in baseline) {
436
+ diagnostics.push(
437
+ createDiagnostic("MOSTRA_VERIFY_BASELINE_MISSING", {
438
+ message: `The last passing version's build (${baseline.missing}) isn't in the home any more, so nothing was compared.`,
439
+ }),
440
+ );
441
+ }
442
+ const compared =
443
+ baseline && !("missing" in baseline) && baseline.versionId !== prepared.versionId
444
+ ? baseline
445
+ : undefined;
446
+ if (baseline && !("missing" in baseline)) regressions.against = baseline.versionId;
447
+ if (prepared.identityKnown) options.clearPark(prepared.artifactId);
448
+
449
+ // 3 to 5: boot, render, smoke and regressions, within 120 s.
450
+ const deadline = Date.now() + (options.limits?.timeoutMs ?? VERIFY_TIMEOUT_MS);
451
+ const candidateDir = join(buildsDir, prepared.versionId);
452
+ let sandbox: Sandbox | undefined;
453
+ let stage = "boot";
454
+ try {
455
+ run.progress?.("boot");
456
+ const bootStart = Date.now();
457
+ sandbox = await startSandbox(options.sandbox, {
458
+ artifactId: prepared.artifactId,
459
+ versions: [
460
+ ...(compared ? [sandboxVersion(compared.versionId, compared.dir)] : []),
461
+ sandboxVersion(prepared.versionId, candidateDir),
462
+ ],
463
+ sourceDir: prepared.sourceDir,
464
+ });
465
+ const health = await fetch(`${sandbox.shellOrigin}/a/${prepared.artifactId}`).catch(
466
+ () => undefined,
467
+ );
468
+ if (!health?.ok) throw new Error("The verify sandbox's shell didn't answer.");
469
+ time("boot", bootStart);
470
+
471
+ const clockMs = Math.floor(started / 1000) * 1000;
472
+ const render = async (
473
+ versionId: string,
474
+ viewport: VerifyViewport,
475
+ name: string,
476
+ collect: RenderRequest["collect"],
477
+ ): Promise<RenderResult> => {
478
+ const result = await options.runner
479
+ .render({
480
+ url: (sandbox as Sandbox).link(versionId),
481
+ viewport,
482
+ clockMs,
483
+ outDir: artifactsDir,
484
+ name,
485
+ collect,
486
+ deadline,
487
+ })
488
+ .catch((error: unknown) => {
489
+ if (error instanceof RpcError && error.diagnostic.code === "MOSTRA_VERIFY_TIMEOUT")
490
+ return { timedOut: true } as RenderResult;
491
+ throw error;
492
+ });
493
+ // Every ARIA snapshot verify keeps is written through the redactor, the baseline's too
494
+ // (D138 item 1, Opus review finding 8); the runner only reads it.
495
+ if (result.aria) {
496
+ const text = options.redactor.redact(result.aria.text);
497
+ await writeFile(result.aria.path, text);
498
+ (result as { aria: { path: string; text: string } }).aria = {
499
+ path: result.aria.path,
500
+ text,
501
+ };
502
+ }
503
+ if (result.timedOut) {
504
+ throw new RpcError(
505
+ createDiagnostic("MOSTRA_VERIFY_TIMEOUT", {
506
+ message: `Verify ran out of its ${Math.round((options.limits?.timeoutMs ?? VERIFY_TIMEOUT_MS) / 1000)} s during the ${stage} stage (${name}).`,
507
+ }),
508
+ );
509
+ }
510
+ return result;
511
+ };
512
+
513
+ stage = "render";
514
+ run.progress?.("render");
515
+ const renderStart = Date.now();
516
+ const candidateShots = new Map<string, RenderResult>();
517
+ const renderCandidate = async (
518
+ index: number,
519
+ viewport: VerifyViewport,
520
+ ): Promise<RenderResult> => {
521
+ const result = await render(prepared.versionId, viewport, viewport.name, {
522
+ screenshot: true,
523
+ aria: true,
524
+ axe: true,
525
+ fields: index === 0,
526
+ });
527
+ candidateShots.set(viewport.name, result);
528
+ diagnostics.push(...result.findings);
529
+ if (result.screenshot) {
530
+ screenshots.push({
531
+ viewport: viewport.name,
532
+ path: result.screenshot.path,
533
+ width: result.screenshot.width,
534
+ height: result.screenshot.height,
535
+ tokensEstimate: estimateImageTokens(
536
+ result.screenshot.width,
537
+ result.screenshot.height,
538
+ ),
539
+ returned: false,
540
+ });
541
+ }
542
+ if (result.aria) {
543
+ aria.push({
544
+ viewport: viewport.name,
545
+ path: result.aria.path,
546
+ summary: ariaSummary(result.aria.text),
547
+ });
548
+ }
549
+ return result;
550
+ };
551
+ // The source's first viewport first: a page that never gets ready ends the browser stages
552
+ // here, rather than waiting the same way at every other render.
553
+ const opening = await renderCandidate(0, viewports[0] as VerifyViewport);
554
+ const baselineShots = new Map<string, RenderResult>();
555
+ if (opening.ready) {
556
+ if (compared) {
557
+ stage = "baseline render";
558
+ for (const viewport of viewports) {
559
+ baselineShots.set(
560
+ viewport.name,
561
+ await render(compared.versionId, viewport, `baseline-${viewport.name}`, {
562
+ screenshot: true,
563
+ aria: true,
564
+ axe: false,
565
+ fields: false,
566
+ }),
567
+ );
568
+ }
569
+ }
570
+ stage = "render";
571
+ for (const [index, viewport] of viewports.entries()) {
572
+ if (index > 0) await renderCandidate(index, viewport);
573
+ }
574
+ }
575
+ time("render", renderStart);
576
+
577
+ if (!opening.ready) throw new NotReady();
578
+ // The second boot with identical inputs, for field IDs that change between renders.
579
+ const first = viewports[0] as VerifyViewport;
580
+ const firstFields: readonly ProbedField[] = candidateShots.get(first.name)?.fields ?? [];
581
+ diagnostics.push(...probedFieldLint(firstFields, first.name, coverage));
582
+ stage = "field stability";
583
+ const again = await render(prepared.versionId, first, `${first.name}-again`, {
584
+ screenshot: false,
585
+ aria: false,
586
+ axe: false,
587
+ fields: true,
588
+ });
589
+ // A difference is confirmed by a third boot before it is reported: an ID that changes is
590
+ // different every time, while one that only arrived late on the first, cold boot (a run
591
+ // started at mount, a worker starting) is the same on the two warm ones (Opus review
592
+ // finding 1).
593
+ if (unstableFieldLint(firstFields, again.fields ?? [], coverage, first.name).length > 0) {
594
+ const third = await render(prepared.versionId, first, `${first.name}-third`, {
595
+ screenshot: false,
596
+ aria: false,
597
+ axe: false,
598
+ fields: true,
599
+ });
600
+ diagnostics.push(
601
+ ...unstableFieldLint(again.fields ?? [], third.fields ?? [], coverage, first.name),
602
+ );
603
+ }
604
+
605
+ if (prepared.manifest.verify?.smoke !== false) {
606
+ stage = "smoke";
607
+ run.progress?.("smoke");
608
+ const smokeStart = Date.now();
609
+ const result = await render(prepared.versionId, first, `${first.name}-smoke`, {
610
+ screenshot: false,
611
+ aria: false,
612
+ axe: false,
613
+ fields: false,
614
+ smoke: {
615
+ ...SMOKE_BUDGET,
616
+ ...(options.limits?.smokeInteractions !== undefined
617
+ ? { maxInteractions: options.limits.smokeInteractions }
618
+ : {}),
619
+ },
620
+ });
621
+ diagnostics.push(...result.findings);
622
+ smoke.interactions = result.smoke?.interactions ?? 0;
623
+ smoke.stateChanges = result.smoke?.stateChanges ?? 0;
624
+ time("smoke", smokeStart);
625
+ }
626
+
627
+ stage = "regression";
628
+ run.progress?.("regression");
629
+ const regressionStart = Date.now();
630
+ if (compared) {
631
+ const contracts = contractRegressions(
632
+ readRegistry(compared.dir),
633
+ built.registry,
634
+ (fieldId) => savedAnswers(prepared.artifactId, fieldId),
635
+ );
636
+ diagnostics.push(...contracts.diagnostics);
637
+ if (contracts.summary.length > 0) regressions.contracts = contracts.summary;
638
+ const ariaSummaries: string[] = [];
639
+ const pixels: { viewport: string; ratio: number }[] = [];
640
+ for (const viewport of viewports) {
641
+ const before = baselineShots.get(viewport.name);
642
+ const after = candidateShots.get(viewport.name);
643
+ if (!before || !after) continue;
644
+ if (before.aria && after.aria) {
645
+ const found = ariaRegression(before.aria.text, after.aria.text, viewport.name);
646
+ if (found) {
647
+ diagnostics.push(found.diagnostic);
648
+ ariaSummaries.push(found.summary);
649
+ }
650
+ }
651
+ if (before.screenshot && after.screenshot) {
652
+ const diff = join(artifactsDir, `diff-${viewport.name}.png`);
653
+ const compared = await options.runner.compare(
654
+ { a: before.screenshot.path, b: after.screenshot.path, diff },
655
+ deadline,
656
+ );
657
+ pixels.push({ viewport: viewport.name, ratio: compared.ratio });
658
+ const found = pixelRegression(
659
+ compared.ratio,
660
+ compared.sizeChanged,
661
+ viewport.name,
662
+ diff,
663
+ );
664
+ if (found) diagnostics.push(found);
665
+ }
666
+ }
667
+ if (ariaSummaries.length > 0) regressions.aria = ariaSummaries.join("; ");
668
+ if (pixels.length > 0) regressions.pixels = pixels;
669
+ }
670
+ time("regression", regressionStart);
671
+
672
+ for (const crash of sandbox.crashes()) {
673
+ if (crash.versionId !== prepared.versionId) continue; // the baseline's isn't this source's
674
+ diagnostics.push(
675
+ createDiagnostic("MOSTRA_RUNTIME_WORKER_CRASHED", {
676
+ message: `The source's server code crashed while verify rendered the page (${crash.kind}): ${crash.cause}`,
677
+ }),
678
+ );
679
+ }
680
+ for (const failure of sandbox.liveFailures()) {
681
+ diagnostics.push(
682
+ createDiagnostic(
683
+ failure.code === "MOSTRA_SECRET_MISSING"
684
+ ? "MOSTRA_VERIFY_SECRET_MISSING"
685
+ : "MOSTRA_VERIFY_LIVE_FAILED",
686
+ {
687
+ message: `The live source ${failure.key} failed while verify rendered the page: ${failure.message}`,
688
+ },
689
+ ),
690
+ );
691
+ }
692
+ } catch (error) {
693
+ if (error instanceof NotReady) {
694
+ // Reported by the render already; nothing after it can run.
695
+ } else if (error instanceof RpcError) diagnostics.push(error.diagnostic);
696
+ else {
697
+ log.error("verify.stage_failed", { stage, error });
698
+ diagnostics.push(
699
+ createDiagnostic("MOSTRA_VERIFY_CRASHED", {
700
+ message: `Verify stopped during the ${stage} stage: ${(error as Error).message ?? String(error)}`,
701
+ }),
702
+ );
703
+ }
704
+ } finally {
705
+ if (sandbox) {
706
+ for (const fn of sandbox.skipped) {
707
+ smoke.skippedActions.push(fn);
708
+ diagnostics.push(
709
+ createDiagnostic("MOSTRA_VERIFY_ACTION_SKIPPED", {
710
+ message: `Verify didn't run the server function ${fn}: it doesn't check dryRun().`,
711
+ }),
712
+ );
713
+ }
714
+ await sandbox.close();
715
+ }
716
+ }
717
+ }
718
+
719
+ timings["total"] = Date.now() - started;
720
+ const merged = mergeDiagnostics(diagnostics).map((diagnostic) => ({
721
+ ...diagnostic,
722
+ message: options.redactor.redact(diagnostic.message),
723
+ }));
724
+ const failed = hasError(merged);
725
+ const policy = run.screenshots ?? "on-failure";
726
+ const verdict: VerifyVerdict = {
727
+ status: failed ? "fail" : "pass",
728
+ artifact: {
729
+ ...(prepared.identityKnown
730
+ ? { id: prepared.artifactId, versionId: prepared.versionId }
731
+ : {}),
732
+ path: prepared.path,
733
+ sourceDigest: prepared.sourceDigest,
734
+ envDigest: prepared.envDigest,
735
+ },
736
+ diagnostics: merged,
737
+ screenshots: screenshots.map((shot) => ({
738
+ ...shot,
739
+ returned: policy === "always" || (policy === "on-failure" && failed),
740
+ })),
741
+ aria,
742
+ smoke,
743
+ regressions,
744
+ timingsMs: timings,
745
+ };
746
+ const checkedVerdict = VerifyVerdict.parse(verdict);
747
+ if (
748
+ !merged.some(
749
+ (diagnostic) => diagnostic.severity === "error" && UNCACHEABLE.test(diagnostic.code),
750
+ )
751
+ ) {
752
+ await mkdir(cacheDir, { recursive: true, mode: 0o700 });
753
+ const target = join(cacheDir, `${key}.json`);
754
+ const temporary = `${target}.${process.pid}-${randomUUID()}.tmp`;
755
+ await writeFile(
756
+ temporary,
757
+ `${JSON.stringify({ verdict: checkedVerdict, built: built.ok }, null, 2)}\n`,
758
+ );
759
+ await rename(temporary, target);
760
+ await pruneVerdicts();
761
+ } else {
762
+ // Its screenshots stay for the caller who reads this verdict; the cache's pruning removes
763
+ // them later, as no cached verdict names them (finding 9).
764
+ await rm(join(cacheDir, `${key}.json`), { force: true });
765
+ await pruneVerdicts();
766
+ }
767
+ log.info("verify.finished", {
768
+ status: verdict.status,
769
+ errors: merged
770
+ .filter((diagnostic) => diagnostic.severity === "error")
771
+ .map((diagnostic) => diagnostic.code),
772
+ totalMs: timings["total"],
773
+ });
774
+ return { verdict: checkedVerdict, built: built.ok };
775
+ };
776
+
777
+ // Runs that share a cache key (identical sources at two paths) share its verdict file and its
778
+ // screenshot directory, so they run one at a time (GPT review finding 2).
779
+ const running = new Map<string, Promise<unknown>>();
780
+ const serialized = (prepared: PreparedSource, run: VerifyRun): Promise<VerifyOutcome> => {
781
+ const key = verdictKey(prepared.sourceDigest, prepared.envDigest);
782
+ const previous = running.get(key) ?? Promise.resolve();
783
+ const next = previous.then(
784
+ () => verify(prepared, run),
785
+ () => verify(prepared, run),
786
+ );
787
+ const settled = next.catch(() => undefined);
788
+ running.set(key, settled);
789
+ void settled.then(() => {
790
+ if (running.get(key) === settled) running.delete(key);
791
+ });
792
+ return next;
793
+ };
794
+
795
+ return {
796
+ cacheDir,
797
+ run: serialized,
798
+ cached(prepared) {
799
+ const file = join(cacheDir, `${verdictKey(prepared.sourceDigest, prepared.envDigest)}.json`);
800
+ let raw: unknown;
801
+ try {
802
+ raw = JSON.parse(readFileSync(file, "utf8"));
803
+ } catch {
804
+ return undefined;
805
+ }
806
+ const entry = raw as { verdict?: unknown; built?: unknown } | null;
807
+ if (typeof entry?.built !== "boolean") return undefined;
808
+ const parsed = VerifyVerdict.safeParse(entry.verdict);
809
+ if (!parsed.success) return undefined;
810
+ const id = parsed.data.artifact.id;
811
+ // A verdict made for another artifact (a copy with the same files) isn't this one's.
812
+ if (id !== undefined && prepared.identityKnown && id !== prepared.artifactId)
813
+ return undefined;
814
+ return { verdict: parsed.data, built: entry.built };
815
+ },
816
+ builtVersion: completeBuild,
817
+ collect: (dryRun) =>
818
+ collectVerifyCaches(home, {
819
+ dryRun,
820
+ inUse: (name) => (inUse.get(name) ?? 0) > 0,
821
+ running: (name) => running.has(name),
822
+ }),
823
+ };
824
+ }
825
+
826
+ /**
827
+ * What gc may take from verify's caches (D140 item 14): least recently used builds past the 5 GB
828
+ * cap and screenshot directories no cached verdict names, never one a run uses. It reads only the
829
+ * home's files, so it works before any verify ran in this process; the caller holds the
830
+ * instance's gate alone, so no run starts meanwhile.
831
+ */
832
+ export async function collectVerifyCaches(
833
+ home: string,
834
+ options: {
835
+ readonly dryRun: boolean;
836
+ readonly inUse?: (build: string) => boolean;
837
+ readonly running?: (key: string) => boolean;
838
+ },
839
+ ): Promise<{ readonly count: number; readonly bytes: number }> {
840
+ const buildsDir = join(home, "cache", "builds");
841
+ const cacheDir = join(home, "cache", "verify");
842
+ const inUse = options.inUse ?? (() => false);
843
+ const running = options.running ?? (() => false);
844
+ const dryRun = options.dryRun;
845
+ const removable: { readonly dir: string; readonly size: number }[] = [];
846
+ const entries = await readdir(buildsDir, { withFileTypes: true }).catch(() => []);
847
+ const builds = await Promise.all(
848
+ entries
849
+ .filter((entry) => entry.isDirectory() && !entry.name.includes(".tmp-"))
850
+ .map(async (entry) => {
851
+ const dir = join(buildsDir, entry.name);
852
+ return {
853
+ dir,
854
+ name: entry.name,
855
+ mtime: (await stat(dir)).mtimeMs,
856
+ size: await sizeOf(dir),
857
+ };
858
+ }),
859
+ );
860
+ let total = builds.reduce((acc, build) => acc + build.size, 0);
861
+ for (const build of builds.sort((a, b) => a.mtime - b.mtime || (a.name < b.name ? -1 : 1))) {
862
+ if (total <= BUILD_CACHE_BYTES) break;
863
+ if (inUse(build.name)) continue;
864
+ removable.push(build);
865
+ total -= build.size;
866
+ }
867
+ const all = await readdir(cacheDir, { withFileTypes: true }).catch(() => []);
868
+ const verdicts = new Set(
869
+ all.filter((entry) => entry.name.endsWith(".json")).map((entry) => entry.name.slice(0, -5)),
870
+ );
871
+ for (const entry of all.sort((a, b) => (a.name < b.name ? -1 : 1))) {
872
+ if (!entry.isDirectory() || verdicts.has(entry.name) || running(entry.name)) continue;
873
+ const dir = join(cacheDir, entry.name);
874
+ if (dir === sandboxRoot(home)) continue;
875
+ removable.push({ dir, size: await sizeOf(dir) });
876
+ }
877
+ if (!dryRun) {
878
+ for (const { dir } of removable) await rm(dir, { recursive: true, force: true });
879
+ }
880
+ return {
881
+ count: removable.length,
882
+ bytes: removable.reduce((acc, item) => acc + item.size, 0),
883
+ };
884
+ }
885
+
886
+ /**
887
+ * Folds identical diagnostics (same code and message) into one. Several renders of one page report
888
+ * the same fault once each, so the fold keeps the largest count rather than adding them.
889
+ */
890
+ function mergeDiagnostics(diagnostics: readonly Diagnostic[]): Diagnostic[] {
891
+ const seen = new Map<string, Diagnostic>();
892
+ for (const diagnostic of diagnostics) {
893
+ const key = `${diagnostic.code}\u0000${diagnostic.message}`;
894
+ const known = seen.get(key);
895
+ if (known) {
896
+ const count = Math.max(known.count ?? 1, diagnostic.count ?? 1);
897
+ seen.set(key, count > 1 ? { ...known, count } : known);
898
+ } else seen.set(key, diagnostic);
899
+ }
900
+ const order = { error: 0, warning: 1, hint: 2 };
901
+ return [...seen.values()].sort((a, b) => order[a.severity] - order[b.severity]);
902
+ }
903
+
904
+ /** The error codes of a verdict, each once, in order: what `--force` records (D41). */
905
+ export function errorCodes(verdict: VerifyVerdict): string[] {
906
+ return [
907
+ ...new Set(
908
+ verdict.diagnostics
909
+ .filter((diagnostic) => diagnostic.severity === "error")
910
+ .map((diagnostic) => diagnostic.code),
911
+ ),
912
+ ];
913
+ }