@mark1russell7/harness 0.14.1 → 0.14.2

package/README.md

@@ -27,6 +27,7 @@ A **cell** (`cell.ts`) is all that one measurement needs, as data:
 - Each hop of the topology, on the network of each of its sides.
 - An injector sidecar in the namespace of the target, with NET_ADMIN. Thus the image of the target stays stock.
 - The manifest of each environment gives the HZ of its kernel, from /proc/config.gz. A host without that file (a hosted runner) gets HZ from two readings of /proc/timer_list, one second apart: its jiffies against the time of the kernel (`hzOf`). `hzFrom` tells which.
+- The manifest of each environment holds a `substrate` block (`substrate.ts`). It gives the layer, the cloud, the vendor, the kernel, HZ, KVM and the image of the runner. GitHub can schedule one image on Azure or on AWS. Thus the cloud comes from the DMI vendor, not from the name of the kernel. No statistic pools two substrates (`comparable`). A record from before the block reads through `substrateOf`, and nothing rewrites it.
 - The prober ([`@mark1russell7/prober`](https://www.npmjs.com/package/@mark1russell7/prober)): a privileged container that loads the kernel program. It watches the namespace of the client, of the target and of each hop. Each run keeps its records from its start to its end. A run whose records the prober lost is void.
 
 Each command is an argv array.

package/build/index.d.ts

@@ -761,6 +761,76 @@ export declare const jitterOf: (cell: Cell, run: Run) => Jitter;
  */
 export declare const requestOf: (events: readonly ProbeEvent[]) => RequestReading | null;
 //#endregion
+//#region src/substrate.d.ts
+/**
+ * A layer is a rung of the laboratory (`docs/S7.md`). E1 is containers on one kernel, and E2 is a
+ * cluster of containers on one kernel. The other layers do not have a runner at this time.
+ */
+type Layer = "E0" | "E1" | "E2" | "E3" | "E4" | "E5" | "E6";
+/** A cloud is where the runner operates. GitHub can schedule a standard Linux job on Azure or on AWS. */
+type Cloud = "azure" | "aws" | "unknown";
+/** A host is what a process reads about its own machine. */
+interface Host {
+  /** This text is the kernel release. */
+  readonly kernel: string | null;
+  /** This number is `CONFIG_HZ` from the configuration of the kernel, or null without that file. */
+  readonly hz: number | null;
+  /** This text is the DMI system vendor, for example `Microsoft Corporation`, or null without that file. */
+  readonly vendor: string | null;
+  /** This value tells if `/dev/kvm` exists. A later VM layer needs it. */
+  readonly kvm: boolean;
+  /** This text is `$ImageOS $ImageVersion` of a hosted runner, or null elsewhere. */
+  readonly image: string | null;
+}
+/**
+ * A substrate tells where a record comes from. The rules of comparison in `docs/S7.md` read it: no
+ * statistic pools two layers, two kernels or two clouds. The digest of each image stays in the
+ * manifest. A value is null in a record from before this block.
+ */
+interface Substrate {
+  readonly layer: Layer;
+  readonly cloud: Cloud;
+  readonly vendor: string | null;
+  readonly kernel: string | null;
+  readonly hz: number | null;
+  readonly kvm: boolean | null;
+  readonly image: string | null;
+}
+/** GitHub announced Linux jobs on AWS on this date. Each earlier hosted job ran on Azure. */
+export declare const AWS_FROM = "2026-10-28";
+/** This function gives the cloud of a DMI vendor. A kernel name does not tell: one image can start on each cloud. */
+export declare const cloudOf: (vendor: string | null) => Cloud;
+/** This function reads the host. `root` and `env` are for tests. */
+export declare const readHost: (root?: string, env?: Readonly<Record<string, string | undefined>>, kernel?: string) => Host;
+/** This function gives the substrate of a layer on a host. */
+export declare const substrateOn: (layer: Layer, host?: Host) => Substrate;
+/** A part of a record that can hold a substrate: a manifest of the harness, or the fields of a kind manifest. */
+interface SubstrateSource {
+  readonly substrate?: Substrate;
+  readonly kernel?: string;
+  readonly hz?: string | null;
+}
+/**
+ * This function reads the substrate of a record, the upgrade of a record from before this block.
+ * Nothing rewrites such a record. It reads as the given layer. Its cloud is Azure if the record is
+ * from before `AWS_FROM`, and unknown after that date, because its runner did not record the cloud.
+ */
+export declare const substrateOf: (source: SubstrateSource, at: string, layer?: Layer) => Substrate;
+/**
+ * This function tells if a statistic can pool two substrates. They must have one layer, one kernel
+ * and one cloud. An unknown value does not refuse a pair, because an old record cannot tell. The
+ * reader of such a pair says so with `substrateKey`.
+ */
+export declare const comparable: (a: Substrate, b: Substrate) => boolean;
+/** This function gives the one-line name of a substrate, for a summary. */
+export declare const substrateKey: (substrate: Substrate) => string;
+/**
+ * This function gives the first two substrates that a statistic cannot pool, or undefined. It
+ * examines each pair. An unknown value matches Azure and AWS, thus one comparison with the first
+ * substrate can miss a pair.
+ */
+export declare const unpoolable: (substrates: readonly Substrate[]) => readonly [Substrate, Substrate] | undefined;
+//#endregion
 //#region src/lab.d.ts
 /**
  * This time is the interval of the listing of a router, when its hop does not set one. A listing
@@ -829,6 +899,8 @@ interface Manifest {
   readonly hzFrom?: "config" | "measured";
   readonly boot_id: string;
   readonly docker: string;
+  /** This block tells the layer, the cloud and the kernel of the record. A record from before it reads through `substrateOf`. */
+  readonly substrate?: Substrate;
   /** This record is the target, and its settings as it read them back. */
   readonly target: {
     readonly image: string;
@@ -1715,5 +1787,5 @@ export declare const spread: (runs: number, environments: number) => number[];
  */
 export declare const runCell: (cell: Cell, say?: (line: string) => void) => Promise<CellResult>;
 //#endregion
-export { type Agent, type BuildImage, type CallReading, type Cell, type CellResult, type Client, type ClientImage, type Cluster, type ClusterClientAt, type ClusterLab, type ClusterStage, type Crossings, type Cut, type Decision, type DriverBand, type DriverSocket, type DriverStep, type DriverStepTime, type ErrorOnTheWay, type Fault, type FaultPlace, type FaultSide, type Group, type GroupClient, type GroupLab, type GroupMeasured, type GroupNetworkFault, type GroupPlace, type GroupPrediction, type GroupReading, type GroupRole, type GroupVerdict, type GroupView, type Hop, type HopEvent, type HopPlace, type HopSignal, type HopWrite, type HttpProbe, type ImagePlan, type ImageSource, type Interval, type Jitter, type KernelRecord, type Lab, type LineMatch, type Manifest, type ManifestHop, type Measured, type MemberLine, type MiddleboxEvent, type MiddleboxExpectation, type MiddleboxForm, type NetworkFault, type NodeLine, type Observer, type Outcome, type Pairing, type PinnedImage, type Prediction, type Probe, type ProbeEvent, type ProgramEvent, type ProxyHop, type ProxyTime, type ReconnectReading, type ReconnectVerdict, type Reconnects, type Recovers, type Reference, type Reordering, type ReplicaSet, type ReplicaSetLab, type ReplicaSetStage, type Replies, type RequestPrediction, type RequestReading, type RouterHop, type RttRange, type Run, type RunGroup, type RunPart, type RunTopology, type SentinelEvent, type SentinelStage, type Shipped, type ShippedImage, type SocketPlace, type Spread, type Stage, type StageBand, type StageVerdict, type Stamp, type Status, type StatusRow, type Subject, type Target, type Topology, type Toxic, type Verdict, type WallStamp, type Writes, type WsProbe, isHopPlace, latestEndOf };
+export { type Agent, type BuildImage, type CallReading, type Cell, type CellResult, type Client, type ClientImage, type Cloud, type Cluster, type ClusterClientAt, type ClusterLab, type ClusterStage, type Crossings, type Cut, type Decision, type DriverBand, type DriverSocket, type DriverStep, type DriverStepTime, type ErrorOnTheWay, type Fault, type FaultPlace, type FaultSide, type Group, type GroupClient, type GroupLab, type GroupMeasured, type GroupNetworkFault, type GroupPlace, type GroupPrediction, type GroupReading, type GroupRole, type GroupVerdict, type GroupView, type Hop, type HopEvent, type HopPlace, type HopSignal, type HopWrite, type Host, type HttpProbe, type ImagePlan, type ImageSource, type Interval, type Jitter, type KernelRecord, type Lab, type Layer, type LineMatch, type Manifest, type ManifestHop, type Measured, type MemberLine, type MiddleboxEvent, type MiddleboxExpectation, type MiddleboxForm, type NetworkFault, type NodeLine, type Observer, type Outcome, type Pairing, type PinnedImage, type Prediction, type Probe, type ProbeEvent, type ProgramEvent, type ProxyHop, type ProxyTime, type ReconnectReading, type ReconnectVerdict, type Reconnects, type Recovers, type Reference, type Reordering, type ReplicaSet, type ReplicaSetLab, type ReplicaSetStage, type Replies, type RequestPrediction, type RequestReading, type RouterHop, type RttRange, type Run, type RunGroup, type RunPart, type RunTopology, type SentinelEvent, type SentinelStage, type Shipped, type ShippedImage, type SocketPlace, type Spread, type Stage, type StageBand, type StageVerdict, type Stamp, type Status, type StatusRow, type Subject, type Substrate, type SubstrateSource, type Target, type Topology, type Toxic, type Verdict, type WallStamp, type Writes, type WsProbe, isHopPlace, latestEndOf };
 //# sourceMappingURL=index.d.ts.map

package/build/index.js

@@ -2,6 +2,9 @@ import { C as targetImageOf, E as unpinnedBases, S as subjectProblems, T as unlo
 import { quantity, valueIn } from "@mark1russell7/quantity";
 import { median, medianInterval as medianInterval$1, quantileSorted } from "@mark1russell7/rigor-statistics";
 import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { release } from "node:os";
+import { join } from "node:path";
 //#region src/cell.ts
 /** This function tells if a fault place is a hop of a topology. */
 const isHopPlace = (place) => typeof place === "object" && "hop" in place;
@@ -2166,6 +2169,78 @@ const measureSocket = (cell, run) => {
 	};
 };
 //#endregion
+//#region src/substrate.ts
+/** GitHub announced Linux jobs on AWS on this date. Each earlier hosted job ran on Azure. */
+const AWS_FROM = "2026-10-28";
+/** This function gives the cloud of a DMI vendor. A kernel name does not tell: one image can start on each cloud. */
+const cloudOf = (vendor) => {
+	if (vendor === null) return "unknown";
+	if (/microsoft/i.test(vendor)) return "azure";
+	if (/amazon/i.test(vendor)) return "aws";
+	return "unknown";
+};
+const textOf = (path) => {
+	try {
+		return readFileSync(path, "utf8").trim();
+	} catch {
+		return null;
+	}
+};
+/** This function reads the host. `root` and `env` are for tests. */
+const readHost = (root = "/", env = process.env, kernel = release()) => {
+	const config = textOf(join(root, "boot", `config-${kernel}`));
+	const hz = config === null ? void 0 : /^CONFIG_HZ=(\d+)$/m.exec(config)?.[1];
+	const os = env["ImageOS"];
+	const version = env["ImageVersion"];
+	return {
+		kernel,
+		hz: hz === void 0 ? null : Number(hz),
+		vendor: textOf(join(root, "sys", "class", "dmi", "id", "sys_vendor")),
+		kvm: existsSync(join(root, "dev", "kvm")),
+		image: os === void 0 || version === void 0 ? null : `${os} ${version}`
+	};
+};
+/** This function gives the substrate of a layer on a host. */
+const substrateOn = (layer, host = readHost()) => ({
+	layer,
+	cloud: cloudOf(host.vendor),
+	...host
+});
+/**
+* This function reads the substrate of a record, the upgrade of a record from before this block.
+* Nothing rewrites such a record. It reads as the given layer. Its cloud is Azure if the record is
+* from before `AWS_FROM`, and unknown after that date, because its runner did not record the cloud.
+*/
+const substrateOf = (source, at, layer = "E1") => source.substrate ?? {
+	layer,
+	cloud: at.slice(0, 10) < "2026-10-28" ? "azure" : "unknown",
+	vendor: null,
+	kernel: source.kernel ?? null,
+	hz: source.hz === void 0 || source.hz === null ? null : Number(source.hz),
+	kvm: null,
+	image: null
+};
+const differ = (a, b, unknown) => a !== null && b !== null && a !== unknown && b !== unknown && a !== b;
+/**
+* This function tells if a statistic can pool two substrates. They must have one layer, one kernel
+* and one cloud. An unknown value does not refuse a pair, because an old record cannot tell. The
+* reader of such a pair says so with `substrateKey`.
+*/
+const comparable = (a, b) => a.layer === b.layer && !differ(a.kernel, b.kernel) && !differ(a.cloud, b.cloud, "unknown");
+/** This function gives the one-line name of a substrate, for a summary. */
+const substrateKey = (substrate) => `${substrate.layer} ${substrate.cloud} ${substrate.kernel ?? "unknown"}`;
+/**
+* This function gives the first two substrates that a statistic cannot pool, or undefined. It
+* examines each pair. An unknown value matches Azure and AWS, thus one comparison with the first
+* substrate can miss a pair.
+*/
+const unpoolable = (substrates) => {
+	for (const [index, a] of substrates.entries()) {
+		const b = substrates.slice(index + 1).find((other) => !comparable(a, other));
+		if (b !== void 0) return [a, b];
+	}
+};
+//#endregion
 //#region src/lab.ts
 /** This function loads Testcontainers when a lab first opens. Code that only measures and judges does not load it. */
 const containers = () => import("testcontainers");
@@ -3071,6 +3146,7 @@ const openLab = async (target, kind = "tcp", topology) => {
 					})(),
 					boot_id: await output(client, ["cat", "/proc/sys/kernel/random/boot_id"]),
 					docker: `${runtime.info.containerRuntime.serverVersion} on ${runtime.info.containerRuntime.operatingSystem}`,
+					substrate: substrateOn("E1"),
 					target: {
 						image: targetImage,
 						...target.subject === void 0 ? {} : {
@@ -4215,6 +4291,7 @@ const openReplicaSetLab = async (set) => {
 					architecture: await output(holder, ["uname", "-m"]),
 					hz: /^CONFIG_HZ=(\d+)$/m.exec(config)?.[1] ?? null,
 					boot_id: await output(holder, ["cat", "/proc/sys/kernel/random/boot_id"]),
+					substrate: substrateOn("E1"),
 					docker: `${runtime.info.containerRuntime.serverVersion} on ${runtime.info.containerRuntime.operatingSystem}`,
 					target: {
 						image: set.image,
@@ -4902,6 +4979,7 @@ const openClusterLab = async (cluster) => {
 					architecture: await output(holder, ["uname", "-m"]),
 					hz: /^CONFIG_HZ=(\d+)$/m.exec(config)?.[1] ?? null,
 					boot_id: await output(holder, ["cat", "/proc/sys/kernel/random/boot_id"]),
+					substrate: substrateOn("E1"),
 					docker: `${runtime.info.containerRuntime.serverVersion} on ${runtime.info.containerRuntime.operatingSystem}`,
 					target: {
 						image: cluster.image,
@@ -5823,6 +5901,6 @@ const runCell = async (cell, say = () => {}) => {
 	}
 };
 //#endregion
-export { CLIENT_NAMES, CLUSTER_STAGES, CONVERGE_MS, DROP_HANDLING, GIVES_AWAY, INJECT, KEPT, LINGER_MS, LISTING, MEMBER_MARKS, MONITOR_DOWN, NODE_MARKS, NOISE, PINNED, PUMP, PUMP_SLACK, QUIET_MS, RELATIVE, REPLICA_SET_STAGES, REPOSITORY, SHIPPED_CLIENTS, SHIPPED_NAMES, STAGES, STATUS_SCRIPT, STEPS, STEP_DOWN, amqpClientImage, callOf, clockOffsetOf, closeOrExit, clusterArgs, clusterConf, clusterCutOf, clusterHostsOf, clusterOnce, clusterStagesOf, clusterViewOf, crossingsOf, cutOf, deadlineOf, delayVoids, deviceOf, dropFinding, dropOf, endpointAfter, errorsOf, exitOf, fieldOf, fieldsOf, firstUnanswered, goHttpImage, groupOnce, groupVerdictOf, grpcClientImage, harnessImage, hikariClientImage, hzOf, imageOf, imageProblems, inContext, infoOf, initiateScript, isHopPlace, jitterOf, jitterOfLines, judge, lagsOf, latestEndOf, leftAfter, logNameOf, matches, measure, measureDriver, measureGroup, medianInterval, memberCommand, memberConfig, memberLineOf, mongoClientImage, monotonicOf, nodeClientImage, nodeCommand, nodeHttpImage, nodeLineOf, nodeNameOf, nodesOnMonotonic, noiseOf, onMonotonic, openClusterLab, openGroupLab, openLab, openReplicaSetLab, pairingOf, pairingsOf, peersOf, pgClientImage, pingsOf, plainOf, planOf, programLines, programOf, quantileOf, reconnectFinding, reconnectOf, referenceOf, reorderingOf, replicaSetArgs, replicaSetOnce, replicaSetStagesOf, requestOf, requestWords, restamped, routerImage, routesOf, runCell, sentinelConfig, socketAt, socketOf, socketsOf, spread, spreadOf, stagesOf, statusViewOf, subjectClient, subjectProblems, subscriptionsOf, targetImageOf, targetSourceOf, templated, toolJsonOf, toxicBody, unlockedManifests, unpinnedBases, verdictOf, viewOf, writesOf };
+export { AWS_FROM, CLIENT_NAMES, CLUSTER_STAGES, CONVERGE_MS, DROP_HANDLING, GIVES_AWAY, INJECT, KEPT, LINGER_MS, LISTING, MEMBER_MARKS, MONITOR_DOWN, NODE_MARKS, NOISE, PINNED, PUMP, PUMP_SLACK, QUIET_MS, RELATIVE, REPLICA_SET_STAGES, REPOSITORY, SHIPPED_CLIENTS, SHIPPED_NAMES, STAGES, STATUS_SCRIPT, STEPS, STEP_DOWN, amqpClientImage, callOf, clockOffsetOf, closeOrExit, cloudOf, clusterArgs, clusterConf, clusterCutOf, clusterHostsOf, clusterOnce, clusterStagesOf, clusterViewOf, comparable, crossingsOf, cutOf, deadlineOf, delayVoids, deviceOf, dropFinding, dropOf, endpointAfter, errorsOf, exitOf, fieldOf, fieldsOf, firstUnanswered, goHttpImage, groupOnce, groupVerdictOf, grpcClientImage, harnessImage, hikariClientImage, hzOf, imageOf, imageProblems, inContext, infoOf, initiateScript, isHopPlace, jitterOf, jitterOfLines, judge, lagsOf, latestEndOf, leftAfter, logNameOf, matches, measure, measureDriver, measureGroup, medianInterval, memberCommand, memberConfig, memberLineOf, mongoClientImage, monotonicOf, nodeClientImage, nodeCommand, nodeHttpImage, nodeLineOf, nodeNameOf, nodesOnMonotonic, noiseOf, onMonotonic, openClusterLab, openGroupLab, openLab, openReplicaSetLab, pairingOf, pairingsOf, peersOf, pgClientImage, pingsOf, plainOf, planOf, programLines, programOf, quantileOf, readHost, reconnectFinding, reconnectOf, referenceOf, reorderingOf, replicaSetArgs, replicaSetOnce, replicaSetStagesOf, requestOf, requestWords, restamped, routerImage, routesOf, runCell, sentinelConfig, socketAt, socketOf, socketsOf, spread, spreadOf, stagesOf, statusViewOf, subjectClient, subjectProblems, subscriptionsOf, substrateKey, substrateOf, substrateOn, targetImageOf, targetSourceOf, templated, toolJsonOf, toxicBody, unlockedManifests, unpinnedBases, unpoolable, verdictOf, viewOf, writesOf };
 
 //# sourceMappingURL=index.js.map