import { mkdir, writeFile } from "node:fs/promises"; import { dirname } from "node:path"; /** * scale-architecture.md ยง48. Machine-readable benchmark result. */ export type BenchmarkProfile = "S0" | "S1" | "S2" | "S3" | "S4"; export interface BenchmarkResult { readonly name: string; readonly profile: BenchmarkProfile; readonly cardinality: number; readonly samples: readonly number[]; readonly medianMs: number; readonly heapBytes?: number; readonly metadata: Readonly>; } export type BenchmarkArtifact = Readonly<{ schemaVersion: 1; suite: string; generatedAt: string; node: string; passed: boolean; results: readonly BenchmarkResult[]; checks: readonly Readonly<{ name: string; passed: boolean; detail: string }>[]; }>; const PROFILES: ReadonlySet = new Set(["S0", "S1", "S2", "S3", "S4"]); export function median(values: readonly number[]): number { if (values.length === 0) throw new TypeError("median of an empty series"); const sorted = [...values].sort((left, right) => left - right); const middle = Math.floor(sorted.length / 2); return sorted.length % 2 === 1 ? (sorted[middle] as number) : ((sorted[middle - 1] as number) + (sorted[middle] as number)) / 2; } export function assertBenchmarkResult(value: BenchmarkResult): BenchmarkResult { if (typeof value.name !== "string" || value.name.length === 0) { throw new TypeError("benchmark name required"); } if (!PROFILES.has(value.profile)) { throw new TypeError(`unknown benchmark profile ${String(value.profile)}`); } if (!Number.isSafeInteger(value.cardinality) || value.cardinality < 0) { throw new TypeError("benchmark cardinality must be a non-negative integer"); } if ( value.samples.length === 0 || value.samples.some((sample) => !Number.isFinite(sample) || sample < 0) ) { throw new TypeError("benchmark samples must be finite non-negative numbers"); } if (value.medianMs !== median(value.samples)) { throw new TypeError("benchmark medianMs must be the median of its samples"); } return value; } export async function writeBenchmarkArtifact( path: string, artifact: BenchmarkArtifact, ): Promise { for (const result of artifact.results) assertBenchmarkResult(result); await mkdir(dirname(path), { recursive: true }); await writeFile(path, `${JSON.stringify(artifact, null, 2)}\n`); }