@venn-lang/load 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vinicius Borges
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# @venn-lang/load
+
+> The `load` namespace: describe a load profile, run it, assert on the metrics.
+
+Three builders turn a sentence about traffic into a profile value, and a fourth verb hands that
+profile to the `LoadRunner` port and gives you back latency percentiles and an error rate. The
+profile is plain data, so a flow can hold it, pass it and read it before anything is driven.
+
+## Install
+
+Nothing to install. `@venn-lang/load` is part of the standard library, and the CLI and the language
+server both load [`@venn-lang/stdlib`](../stdlib), which lists every stdlib plugin. A file reaches the
+namespace with one line.
+
+```ruby
+use "venn/load"
+```
+
+## Usage
+
+```ruby
+module demo.load
+
+use "venn/load"
+use "venn/assert"
+
+flow "Checkout under load" {
+  step "ramp to 200 VUs" {
+    const profile = load.ramp 0 200 { over: "30s", hold: "5m" }
+    const metrics = load.run profile
+
+    expect metrics.p95 < 800
+    expect metrics.errorRate < 0.05
+  }
+}
+```
+
+## Verbs
+
+| Verb | Call | Result |
+| --- | --- | --- |
+| `load.ramp` | `load.ramp 0 200 { over: "30s", hold: "5m" }` | `load.Ramp` |
+| `load.constant` | `load.constant 50 { over: "10s" }` | `load.Constant` |
+| `load.spike` | `load.spike 500 { at: "5s" }` | `load.Spike` |
+| `load.run` | `load.run profile` | `load.Metrics` |
+
+The three builders are pure: they compute a descriptor and touch nothing. Only `load.run` reaches
+the port.
+
+`load.ramp` takes two positional arguments, the virtual users it starts from and the number it ends
+at. The spec's `0 -> 200` arrow sugar is not in the grammar.
+
+**Durations are written as strings.** `over`, `hold` and `at` are read by the SDK's `Duration`
+schema, which accepts `"30s"`, `"2m"` or a plain count of milliseconds and yields milliseconds. The
+language's own `30s` unit literal is a different value, and passing it is refused before the run
+with `"over" is not a valid option`. Write `{ over: "30s" }` or `{ over: 30000 }`.
+
+## The types it publishes
+
+| Type | Shape |
+| --- | --- |
+| `load.Ramp` | `{ kind: "ramp", from, to, over?, hold? }` |
+| `load.Constant` | `{ kind: "constant", vus, over? }` |
+| `load.Spike` | `{ kind: "spike", peak, at? }` |
+| `load.Profile` | Whichever of the three a builder produced. This is what `load.run` takes. |
+| `load.Metrics` | `{ vus, rps, p50, p95, p99, errorRate }` |
+
+The durations inside a profile are numbers, not durations: `Duration` already turned `"30s"` into
+`30000` on the way in, so what a profile holds is a count of milliseconds.
+
+## The LoadRunner port
+
+| | |
+| --- | --- |
+| id | `venn.port.load-runner` |
+| version | 1 |
+| requires | `net` |
+| methods | `run` |
+
+Two implementations ship together, which is what makes this a port rather than a module with a good
+interface:
+
+- `createFakeLoadRunner()` derives canned metrics from the profile's peak VUs, with no real traffic.
+  This is the one [`@venn-lang/stdlib`](../stdlib) binds, so a load flow is runnable offline.
+- `createRealLoadRunner()` is a stub. Every call throws a `VennError` with code `VN8090`, because
+  this repository is the language and drives no real load.
+
+Both run the same conformance suite, `loadRunnerConformance` in `src/runner/load-runner.suite.ts`,
+which holds them to two invariants: `p50 <= p95 <= p99`, and the reported `vus` is the profile's
+peak.
+
+## API
+
+| Export | What it is |
+| --- | --- |
+| `loadPlugin` | The plugin definition: namespace `load`, `requires: ["net"]`. Also the default export. |
+| `rampProfile({ from, to, over?, hold? })` | Builds a `RampProfile`. |
+| `constantProfile({ vus, over? })` | Builds a `ConstantProfile`. |
+| `spikeProfile({ peak, at? })` | Builds a `SpikeProfile`. |
+| `peakVus(profile)` | The peak concurrent VUs a profile reaches, which is what a runner drives toward. |
+| `RampProfile`, `ConstantProfile`, `SpikeProfile` | The three descriptor types. |
+| `LoadProfile` | Their union: what the runner consumes. |
+| `LoadRunnerPort` | The port descriptor. |
+| `LoadRunner` | The port interface: `run(profile)`. |
+| `createFakeLoadRunner()` | The fake runner. |
+| `createRealLoadRunner()` | The real runner, stubbed to throw `VN8090`. |
+| `LoadMetrics` | The metrics type. |
+| `LoadMetricsSchema` | The Zod schema registered as the plugin's nominal `LoadMetrics` type. |
+
+Binding a different runner means one entry in the runner's port list:
+
+```ts
+import { createFakeLoadRunner, LoadRunnerPort } from "@venn-lang/load";
+import { createRunner } from "@venn-lang/runtime";
+
+const runner = createRunner({
+  host,
+  plugins,
+  sink,
+  uri,
+  ports: [{ port: LoadRunnerPort, impl: createFakeLoadRunner() }],
+});
+```
+
+## See also
+
+- [`@venn-lang/sdk`](../sdk) for `definePlugin`, `defineAction` and the `Duration` schema.
+- [`@venn-lang/http`](../std-http) for the requests a load profile is usually pointed at.
+- [`@venn-lang/artifacts`](../std-artifacts) for filing what a run produced.

package/dist/index.d.ts

@@ -0,0 +1,124 @@
+import { PluginDefinition, ZodType } from "@venn-lang/sdk";
+import { Port } from "@venn-lang/contracts";
+//#region src/metrics/load-metrics.types.d.ts
+/**
+ * What a load run reports back. Latencies are in milliseconds and the ordering
+ * `p50 <= p95 <= p99` always holds; the conformance suite enforces it.
+ */
+interface LoadMetrics {
+  /** Peak concurrent virtual users the run reached. */
+  vus: number;
+  /** Requests per second, averaged over the run. */
+  rps: number;
+  p50: number;
+  p95: number;
+  p99: number;
+  /** Share of failed requests, from 0 to 1. */
+  errorRate: number;
+}
+//#endregion
+//#region src/metrics/load-metrics.schema.d.ts
+/** Runtime validator for the nominal `load.Metrics` type. */
+declare const LoadMetricsSchema: ZodType<LoadMetrics>;
+//#endregion
+//#region src/plugin.d.ts
+/**
+ * The `@venn-lang/load` plugin. Registers the `load` namespace: three profile
+ * builders, the `run` verb that executes one, and the profile and metrics
+ * types. Requires the `net` capability, since a run drives real traffic.
+ */
+declare const loadPlugin: PluginDefinition;
+//#endregion
+//#region src/profiles/load-profile.types.d.ts
+/** A ramp from `from` to `to` VUs over `over`, then held for `hold` (ms). */
+interface RampProfile {
+  kind: "ramp";
+  from: number;
+  to: number;
+  over?: number;
+  hold?: number;
+}
+/** A constant `vus` load sustained over `over` (ms). */
+interface ConstantProfile {
+  kind: "constant";
+  vus: number;
+  over?: number;
+}
+/** A single spike to `peak` VUs at `at` (ms into the run). */
+interface SpikeProfile {
+  kind: "spike";
+  peak: number;
+  at?: number;
+}
+/** Whatever a builder produced. `kind` tells the runner which shape it holds. */
+type LoadProfile = RampProfile | ConstantProfile | SpikeProfile;
+//#endregion
+//#region src/profiles/build-profiles.d.ts
+/**
+ * Builds a ramp profile: a climb from `from` to `to` virtual users across
+ * `over` milliseconds, then held at `to` for `hold` milliseconds.
+ *
+ * @returns the profile. Nothing is executed here.
+ */
+declare function rampProfile(args: {
+  from: number;
+  to: number;
+  over?: number;
+  hold?: number;
+}): RampProfile;
+/** Builds a flat profile: `vus` virtual users held for `over` milliseconds. */
+declare function constantProfile(args: {
+  vus: number;
+  over?: number;
+}): ConstantProfile;
+/** Builds a burst profile: one spike to `peak` virtual users, `at` ms into the run. */
+declare function spikeProfile(args: {
+  peak: number;
+  at?: number;
+}): SpikeProfile;
+/**
+ * The highest concurrency a profile calls for, whichever shape it is. This is
+ * the number a runner sizes itself against.
+ */
+declare function peakVus(profile: LoadProfile): number;
+//#endregion
+//#region src/runner/load-runner.types.d.ts
+/** What turns a profile into traffic. */
+interface LoadRunner {
+  /**
+   * Executes one profile to completion.
+   *
+   * @returns the metrics observed, with `p50 <= p95 <= p99`.
+   * @throws {VennError} `VN8090` from an implementation that cannot run.
+   */
+  run(profile: LoadProfile): Promise<LoadMetrics>;
+}
+//#endregion
+//#region src/runner/fake-runner.d.ts
+/**
+ * The offline `LoadRunner`. Derives plausible metrics from the profile's peak
+ * concurrency and sends no traffic.
+ *
+ * @returns a runner whose results are deterministic for a given profile.
+ */
+declare function createFakeLoadRunner(): LoadRunner;
+//#endregion
+//#region src/runner/load-runner.port.d.ts
+/**
+ * The port `load.run` drives traffic through. Requires the `net` capability, so
+ * a host without it fails to load the plugin rather than failing mid-run.
+ */
+declare const LoadRunnerPort: Port<LoadRunner>;
+//#endregion
+//#region src/runner/real-runner.d.ts
+/**
+ * The traffic-generating `LoadRunner`. Not wired up in this build.
+ *
+ * @returns a runner whose `run` throws, so the gap is a legible failure rather
+ * than metrics nobody measured.
+ * @throws {VennError} `VN8090` on every `run`.
+ */
+declare function createRealLoadRunner(): LoadRunner;
+//#endregion
+export { type ConstantProfile, type LoadMetrics, LoadMetricsSchema, type LoadProfile, type LoadRunner, LoadRunnerPort, type RampProfile, type SpikeProfile, constantProfile, createFakeLoadRunner, createRealLoadRunner, loadPlugin as default, loadPlugin, peakVus, rampProfile, spikeProfile };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/metrics/load-metrics.types.ts","../src/metrics/load-metrics.schema.ts","../src/plugin.ts","../src/profiles/load-profile.types.ts","../src/profiles/build-profiles.ts","../src/runner/load-runner.types.ts","../src/runner/fake-runner.ts","../src/runner/load-runner.port.ts","../src/runner/real-runner.ts"],"mappings":";;;;;;;UAIiB;;EAEf;;EAEA;EACA;EACA;EACA;;EAEA;;;;;cCTW,mBAAmB,QAAQ;;;;;;;;cCM3B,YAAY;;;;UCTR;EACf;EACA;EACA;EACA;EACA;;;UAIe;EACf;EACA;EACA;;;UAIe;EACf;EACA;EACA;;;KAIU,cAAc,cAAc,kBAAkB;;;;;;;;;iBCX1C,YAAY;EAC1B;EACA;EACA;EACA;IACE;;iBAKY,gBAAgB;EAAQ;EAAa;IAAkB;;iBAKvD,aAAa;EAAQ;EAAc;IAAgB;;;;;iBAQnD,QAAQ,SAAS;;;;UChChB;;;;;;;EAOf,IAAI,SAAS,cAAc,QAAQ;;;;;;;;;;iBCDrB,wBAAwB;;;;;;;cCH3B,gBAAgB,KAAK;;;;;;;;;;iBCGlB,wBAAwB"}

package/dist/index.js

@@ -0,0 +1,280 @@
+import { Duration, arg, defineAction, definePlugin, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { VennError } from "@venn-lang/contracts";
+//#region src/metrics/load-metrics.schema.ts
+/** Runtime validator for the nominal `load.Metrics` type. */
+const LoadMetricsSchema = z.object({
+	vus: z.number(),
+	rps: z.number(),
+	p50: z.number(),
+	p95: z.number(),
+	p99: z.number(),
+	errorRate: z.number()
+});
+//#endregion
+//#region src/profiles/build-profiles.ts
+/**
+* Builds a ramp profile: a climb from `from` to `to` virtual users across
+* `over` milliseconds, then held at `to` for `hold` milliseconds.
+*
+* @returns the profile. Nothing is executed here.
+*/
+function rampProfile(args) {
+	return {
+		kind: "ramp",
+		from: args.from,
+		to: args.to,
+		over: args.over,
+		hold: args.hold
+	};
+}
+/** Builds a flat profile: `vus` virtual users held for `over` milliseconds. */
+function constantProfile(args) {
+	return {
+		kind: "constant",
+		vus: args.vus,
+		over: args.over
+	};
+}
+/** Builds a burst profile: one spike to `peak` virtual users, `at` ms into the run. */
+function spikeProfile(args) {
+	return {
+		kind: "spike",
+		peak: args.peak,
+		at: args.at
+	};
+}
+/**
+* The highest concurrency a profile calls for, whichever shape it is. This is
+* the number a runner sizes itself against.
+*/
+function peakVus(profile) {
+	if (profile.kind === "ramp") return profile.to;
+	if (profile.kind === "constant") return profile.vus;
+	return profile.peak;
+}
+/**
+* `load.constant 50 { over: "10s" }`.
+*
+* Describes a flat load: `vus` virtual users held steady for `over`. Nothing
+* runs until the profile is handed to `load.run`.
+*
+* @returns a `load.Constant` profile.
+*/
+const constantAction = defineAction({
+	name: "constant",
+	doc: "Build a constant-VUs load profile.",
+	params: z.object({ over: Duration.optional() }).optional(),
+	args: [arg("vus", t.number, "How many virtual users, held steady.")],
+	result: t.ref("load.Constant"),
+	run: (_ctx, input) => buildConstant(input)
+});
+function buildConstant(input) {
+	const params = input.params ?? {};
+	return constantProfile({
+		vus: Number(input.args[0] ?? 0),
+		over: params.over
+	});
+}
+/**
+* `load.ramp 0 200 { over: "30s", hold: "5m" }`.
+*
+* Describes a climb from `from` to `to` virtual users across `over`, then held
+* at `to` for `hold`. Nothing runs until the profile is handed to `load.run`.
+*
+* The grammar has no `0 -> 200` arrow sugar, so the two ends are separate
+* positional arguments. `over` and `hold` accept `"30s"` or a millisecond count.
+*
+* @returns a `load.Ramp` profile.
+*/
+const rampAction = defineAction({
+	name: "ramp",
+	doc: "Build a ramp load profile from `from` to `to` VUs.",
+	params: z.object({
+		over: Duration.optional(),
+		hold: Duration.optional()
+	}).optional(),
+	args: [arg("from", t.number, "Virtual users at the start."), arg("to", t.number, "Virtual users at the end.")],
+	result: t.ref("load.Ramp"),
+	run: (_ctx, input) => buildRamp(input)
+});
+function buildRamp(input) {
+	const params = input.params ?? {};
+	return rampProfile({
+		from: Number(input.args[0] ?? 0),
+		to: Number(input.args[1] ?? 0),
+		over: params.over,
+		hold: params.hold
+	});
+}
+//#endregion
+//#region src/runner/fake-runner.ts
+/**
+* The offline `LoadRunner`. Derives plausible metrics from the profile's peak
+* concurrency and sends no traffic.
+*
+* @returns a runner whose results are deterministic for a given profile.
+*/
+function createFakeLoadRunner() {
+	return { run: async (profile) => metricsFor(profile) };
+}
+function metricsFor(profile) {
+	const vus = peakVus(profile);
+	return {
+		vus,
+		rps: vus * 10,
+		p50: 50,
+		p95: 120,
+		p99: 200,
+		errorRate: .01
+	};
+}
+//#endregion
+//#region src/runner/load-runner.port.ts
+/**
+* The port `load.run` drives traffic through. Requires the `net` capability, so
+* a host without it fails to load the plugin rather than failing mid-run.
+*/
+const LoadRunnerPort = {
+	id: "venn.port.load-runner",
+	version: 1,
+	requires: ["net"],
+	methods: ["run"]
+};
+//#endregion
+//#region src/runner/real-runner.ts
+/**
+* The traffic-generating `LoadRunner`. Not wired up in this build.
+*
+* @returns a runner whose `run` throws, so the gap is a legible failure rather
+* than metrics nobody measured.
+* @throws {VennError} `VN8090` on every `run`.
+*/
+function createRealLoadRunner() {
+	return { run: async () => notImplemented() };
+}
+function notImplemented() {
+	throw new VennError({
+		code: "VN8090",
+		message: "The load runner is not implemented in this build."
+	});
+}
+//#endregion
+//#region src/actions/run.ts
+/**
+* `load.run (load.ramp 0 200 { over: "30s" })`.
+*
+* Drives one profile through the `LoadRunner` port. This is the verb that
+* generates traffic; the builders only describe a shape.
+*
+* @returns the `load.Metrics` the run produced.
+* @throws {VennError} `VN8090` when the host's runner cannot execute a profile.
+*/
+const runAction = defineAction({
+	name: "run",
+	doc: "Run a load profile and return its metrics.",
+	args: [arg("profile", t.ref("load.Profile"), "A profile, as `load.ramp` and friends build.")],
+	result: t.ref("load.Metrics"),
+	run: (ctx, input) => ctx.port(LoadRunnerPort).run(profileOf(input))
+});
+function profileOf(input) {
+	return input.args[0];
+}
+/**
+* `load.spike 500 { at: "5s" }`.
+*
+* Describes a single burst to `peak` virtual users, `at` into the run. Nothing
+* runs until the profile is handed to `load.run`.
+*
+* @returns a `load.Spike` profile.
+*/
+const spikeAction = defineAction({
+	name: "spike",
+	doc: "Build a spike load profile that peaks at `peak` VUs.",
+	params: z.object({ at: Duration.optional() }).optional(),
+	args: [arg("peak", t.number, "Virtual users at the top of the spike.")],
+	result: t.ref("load.Spike"),
+	run: (_ctx, input) => buildSpike(input)
+});
+function buildSpike(input) {
+	const params = input.params ?? {};
+	return spikeProfile({
+		peak: Number(input.args[0] ?? 0),
+		at: params.at
+	});
+}
+//#endregion
+//#region src/actions/index.ts
+/** Every verb in the `load` namespace, in the order the plugin registers them. */
+const loadActions = [
+	rampAction,
+	constantAction,
+	spikeAction,
+	runAction
+];
+//#endregion
+//#region src/types.ts
+/**
+* The types `@venn-lang/load` publishes to the checker, under the `load` namespace:
+* the three profiles its builders return, the union `load.run` accepts, and the
+* metrics it yields. They mirror `profiles/load-profile.types.ts` and
+* `metrics/load-metrics.types.ts` field by field, dropping the `Load` and
+* `Profile` affixes the namespace already says: a flow reads `load.Ramp`.
+*
+* Durations are `number` here on purpose. The `Duration` schema accepts `"30s"`
+* or a plain millisecond count, not the language's own `duration` value, and
+* yields milliseconds. What a profile holds is therefore a count.
+*/
+const loadTypeDefs = {
+	/** A ramp from `from` to `to` VUs over `over`, then held for `hold`. */
+	Ramp: t.record({
+		kind: t.literal("ramp"),
+		from: t.number,
+		to: t.number,
+		over: t.number,
+		hold: t.number
+	}, { optional: ["over", "hold"] }),
+	/** A constant `vus` load sustained over `over`. */
+	Constant: t.record({
+		kind: t.literal("constant"),
+		vus: t.number,
+		over: t.number
+	}, { optional: ["over"] }),
+	/** A single spike to `peak` VUs at `at` into the run. */
+	Spike: t.record({
+		kind: t.literal("spike"),
+		peak: t.number,
+		at: t.number
+	}, { optional: ["at"] }),
+	/** Whatever a builder produced. This is what `load.run` takes. */
+	Profile: t.union(t.ref("load.Ramp"), t.ref("load.Constant"), t.ref("load.Spike")),
+	/** What a run yields. The invariant `p50 <= p95 <= p99` always holds. */
+	Metrics: t.record({
+		vus: t.number,
+		rps: t.number,
+		p50: t.number,
+		p95: t.number,
+		p99: t.number,
+		errorRate: t.number
+	})
+};
+//#endregion
+//#region src/plugin.ts
+/**
+* The `@venn-lang/load` plugin. Registers the `load` namespace: three profile
+* builders, the `run` verb that executes one, and the profile and metrics
+* types. Requires the `net` capability, since a run drives real traffic.
+*/
+const loadPlugin = definePlugin({
+	name: "venn/load",
+	version: "0.0.0",
+	namespace: "load",
+	requires: ["net"],
+	actions: loadActions,
+	types: { LoadMetrics: LoadMetricsSchema },
+	typeDefs: loadTypeDefs
+});
+//#endregion
+export { LoadMetricsSchema, LoadRunnerPort, constantProfile, createFakeLoadRunner, createRealLoadRunner, loadPlugin as default, loadPlugin, peakVus, rampProfile, spikeProfile };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/metrics/load-metrics.schema.ts","../src/profiles/build-profiles.ts","../src/actions/constant.ts","../src/actions/ramp.ts","../src/runner/fake-runner.ts","../src/runner/load-runner.port.ts","../src/runner/real-runner.ts","../src/actions/run.ts","../src/actions/spike.ts","../src/actions/index.ts","../src/types.ts","../src/plugin.ts"],"sourcesContent":["import { type ZodType, z } from \"@venn-lang/sdk\";\nimport type { LoadMetrics } from \"./load-metrics.types.js\";\n\n/** Runtime validator for the nominal `load.Metrics` type. */\nexport const LoadMetricsSchema: ZodType<LoadMetrics> = z.object({\n  vus: z.number(),\n  rps: z.number(),\n  p50: z.number(),\n  p95: z.number(),\n  p99: z.number(),\n  errorRate: z.number(),\n});\n","import type {\n  ConstantProfile,\n  LoadProfile,\n  RampProfile,\n  SpikeProfile,\n} from \"./load-profile.types.js\";\n\n/**\n * Builds a ramp profile: a climb from `from` to `to` virtual users across\n * `over` milliseconds, then held at `to` for `hold` milliseconds.\n *\n * @returns the profile. Nothing is executed here.\n */\nexport function rampProfile(args: {\n  from: number;\n  to: number;\n  over?: number;\n  hold?: number;\n}): RampProfile {\n  return { kind: \"ramp\", from: args.from, to: args.to, over: args.over, hold: args.hold };\n}\n\n/** Builds a flat profile: `vus` virtual users held for `over` milliseconds. */\nexport function constantProfile(args: { vus: number; over?: number }): ConstantProfile {\n  return { kind: \"constant\", vus: args.vus, over: args.over };\n}\n\n/** Builds a burst profile: one spike to `peak` virtual users, `at` ms into the run. */\nexport function spikeProfile(args: { peak: number; at?: number }): SpikeProfile {\n  return { kind: \"spike\", peak: args.peak, at: args.at };\n}\n\n/**\n * The highest concurrency a profile calls for, whichever shape it is. This is\n * the number a runner sizes itself against.\n */\nexport function peakVus(profile: LoadProfile): number {\n  if (profile.kind === \"ramp\") return profile.to;\n  if (profile.kind === \"constant\") return profile.vus;\n  return profile.peak;\n}\n","import {\n  type ActionDefinition,\n  type ActionInput,\n  arg,\n  Duration,\n  defineAction,\n  z,\n} from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { type ConstantProfile, constantProfile } from \"../profiles/index.js\";\n\nconst constantParams = z.object({ over: Duration.optional() });\n\n/**\n * `load.constant 50 { over: \"10s\" }`.\n *\n * Describes a flat load: `vus` virtual users held steady for `over`. Nothing\n * runs until the profile is handed to `load.run`.\n *\n * @returns a `load.Constant` profile.\n */\nexport const constantAction: ActionDefinition = defineAction({\n  name: \"constant\",\n  doc: \"Build a constant-VUs load profile.\",\n  params: constantParams.optional(),\n  args: [arg(\"vus\", t.number, \"How many virtual users, held steady.\")],\n  result: t.ref(\"load.Constant\"),\n  run: (_ctx, input) => buildConstant(input),\n});\n\nfunction buildConstant(input: ActionInput<unknown>): ConstantProfile {\n  const params = (input.params ?? {}) as { over?: number };\n  return constantProfile({ vus: Number(input.args[0] ?? 0), over: params.over });\n}\n","import {\n  type ActionDefinition,\n  type ActionInput,\n  arg,\n  Duration,\n  defineAction,\n  z,\n} from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { type RampProfile, rampProfile } from \"../profiles/index.js\";\n\nconst rampParams = z.object({ over: Duration.optional(), hold: Duration.optional() });\n\n/**\n * `load.ramp 0 200 { over: \"30s\", hold: \"5m\" }`.\n *\n * Describes a climb from `from` to `to` virtual users across `over`, then held\n * at `to` for `hold`. Nothing runs until the profile is handed to `load.run`.\n *\n * The grammar has no `0 -> 200` arrow sugar, so the two ends are separate\n * positional arguments. `over` and `hold` accept `\"30s\"` or a millisecond count.\n *\n * @returns a `load.Ramp` profile.\n */\nexport const rampAction: ActionDefinition = defineAction({\n  name: \"ramp\",\n  doc: \"Build a ramp load profile from `from` to `to` VUs.\",\n  params: rampParams.optional(),\n  args: [\n    arg(\"from\", t.number, \"Virtual users at the start.\"),\n    arg(\"to\", t.number, \"Virtual users at the end.\"),\n  ],\n  result: t.ref(\"load.Ramp\"),\n  run: (_ctx, input) => buildRamp(input),\n});\n\nfunction buildRamp(input: ActionInput<unknown>): RampProfile {\n  const params = (input.params ?? {}) as { over?: number; hold?: number };\n  return rampProfile({\n    from: Number(input.args[0] ?? 0),\n    to: Number(input.args[1] ?? 0),\n    over: params.over,\n    hold: params.hold,\n  });\n}\n","import type { LoadMetrics } from \"../metrics/index.js\";\nimport { type LoadProfile, peakVus } from \"../profiles/index.js\";\nimport type { LoadRunner } from \"./load-runner.types.js\";\n\n/**\n * The offline `LoadRunner`. Derives plausible metrics from the profile's peak\n * concurrency and sends no traffic.\n *\n * @returns a runner whose results are deterministic for a given profile.\n */\nexport function createFakeLoadRunner(): LoadRunner {\n  return {\n    run: async (profile) => metricsFor(profile),\n  };\n}\n\nfunction metricsFor(profile: LoadProfile): LoadMetrics {\n  const vus = peakVus(profile);\n  return { vus, rps: vus * 10, p50: 50, p95: 120, p99: 200, errorRate: 0.01 };\n}\n","import type { Port } from \"@venn-lang/contracts\";\nimport type { LoadRunner } from \"./load-runner.types.js\";\n\n/**\n * The port `load.run` drives traffic through. Requires the `net` capability, so\n * a host without it fails to load the plugin rather than failing mid-run.\n */\nexport const LoadRunnerPort: Port<LoadRunner> = {\n  id: \"venn.port.load-runner\",\n  version: 1,\n  requires: [\"net\"],\n  methods: [\"run\"],\n};\n","import { VennError } from \"@venn-lang/contracts\";\nimport type { LoadRunner } from \"./load-runner.types.js\";\n\n/**\n * The traffic-generating `LoadRunner`. Not wired up in this build.\n *\n * @returns a runner whose `run` throws, so the gap is a legible failure rather\n * than metrics nobody measured.\n * @throws {VennError} `VN8090` on every `run`.\n */\nexport function createRealLoadRunner(): LoadRunner {\n  return {\n    run: async () => notImplemented(),\n  };\n}\n\nfunction notImplemented(): never {\n  throw new VennError({\n    code: \"VN8090\",\n    message: \"The load runner is not implemented in this build.\",\n  });\n}\n","import { type ActionDefinition, type ActionInput, arg, defineAction } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport type { LoadProfile } from \"../profiles/index.js\";\nimport { LoadRunnerPort } from \"../runner/index.js\";\n\n/**\n * `load.run (load.ramp 0 200 { over: \"30s\" })`.\n *\n * Drives one profile through the `LoadRunner` port. This is the verb that\n * generates traffic; the builders only describe a shape.\n *\n * @returns the `load.Metrics` the run produced.\n * @throws {VennError} `VN8090` when the host's runner cannot execute a profile.\n */\nexport const runAction: ActionDefinition = defineAction({\n  name: \"run\",\n  doc: \"Run a load profile and return its metrics.\",\n  args: [arg(\"profile\", t.ref(\"load.Profile\"), \"A profile, as `load.ramp` and friends build.\")],\n  result: t.ref(\"load.Metrics\"),\n  run: (ctx, input) => ctx.port(LoadRunnerPort).run(profileOf(input)),\n});\n\nfunction profileOf(input: ActionInput<unknown>): LoadProfile {\n  return input.args[0] as LoadProfile;\n}\n","import {\n  type ActionDefinition,\n  type ActionInput,\n  arg,\n  Duration,\n  defineAction,\n  z,\n} from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { type SpikeProfile, spikeProfile } from \"../profiles/index.js\";\n\nconst spikeParams = z.object({ at: Duration.optional() });\n\n/**\n * `load.spike 500 { at: \"5s\" }`.\n *\n * Describes a single burst to `peak` virtual users, `at` into the run. Nothing\n * runs until the profile is handed to `load.run`.\n *\n * @returns a `load.Spike` profile.\n */\nexport const spikeAction: ActionDefinition = defineAction({\n  name: \"spike\",\n  doc: \"Build a spike load profile that peaks at `peak` VUs.\",\n  params: spikeParams.optional(),\n  args: [arg(\"peak\", t.number, \"Virtual users at the top of the spike.\")],\n  result: t.ref(\"load.Spike\"),\n  run: (_ctx, input) => buildSpike(input),\n});\n\nfunction buildSpike(input: ActionInput<unknown>): SpikeProfile {\n  const params = (input.params ?? {}) as { at?: number };\n  return spikeProfile({ peak: Number(input.args[0] ?? 0), at: params.at });\n}\n","import type { ActionDefinition } from \"@venn-lang/sdk\";\nimport { constantAction } from \"./constant.js\";\nimport { rampAction } from \"./ramp.js\";\nimport { runAction } from \"./run.js\";\nimport { spikeAction } from \"./spike.js\";\n\n/** Every verb in the `load` namespace, in the order the plugin registers them. */\nexport const loadActions: ActionDefinition[] = [rampAction, constantAction, spikeAction, runAction];\n","import { type TypeSpec, t } from \"@venn-lang/types\";\n\n/**\n * The types `@venn-lang/load` publishes to the checker, under the `load` namespace:\n * the three profiles its builders return, the union `load.run` accepts, and the\n * metrics it yields. They mirror `profiles/load-profile.types.ts` and\n * `metrics/load-metrics.types.ts` field by field, dropping the `Load` and\n * `Profile` affixes the namespace already says: a flow reads `load.Ramp`.\n *\n * Durations are `number` here on purpose. The `Duration` schema accepts `\"30s\"`\n * or a plain millisecond count, not the language's own `duration` value, and\n * yields milliseconds. What a profile holds is therefore a count.\n */\nexport const loadTypeDefs: Readonly<Record<string, TypeSpec>> = {\n  /** A ramp from `from` to `to` VUs over `over`, then held for `hold`. */\n  Ramp: t.record(\n    { kind: t.literal(\"ramp\"), from: t.number, to: t.number, over: t.number, hold: t.number },\n    { optional: [\"over\", \"hold\"] },\n  ),\n  /** A constant `vus` load sustained over `over`. */\n  Constant: t.record(\n    { kind: t.literal(\"constant\"), vus: t.number, over: t.number },\n    { optional: [\"over\"] },\n  ),\n  /** A single spike to `peak` VUs at `at` into the run. */\n  Spike: t.record({ kind: t.literal(\"spike\"), peak: t.number, at: t.number }, { optional: [\"at\"] }),\n  /** Whatever a builder produced. This is what `load.run` takes. */\n  Profile: t.union(t.ref(\"load.Ramp\"), t.ref(\"load.Constant\"), t.ref(\"load.Spike\")),\n  /** What a run yields. The invariant `p50 <= p95 <= p99` always holds. */\n  Metrics: t.record({\n    vus: t.number,\n    rps: t.number,\n    p50: t.number,\n    p95: t.number,\n    p99: t.number,\n    errorRate: t.number,\n  }),\n};\n","import { definePlugin, type PluginDefinition } from \"@venn-lang/sdk\";\nimport { loadActions } from \"./actions/index.js\";\nimport { LoadMetricsSchema } from \"./metrics/index.js\";\nimport { loadTypeDefs } from \"./types.js\";\n\n/**\n * The `@venn-lang/load` plugin. Registers the `load` namespace: three profile\n * builders, the `run` verb that executes one, and the profile and metrics\n * types. Requires the `net` capability, since a run drives real traffic.\n */\nexport const loadPlugin: PluginDefinition = definePlugin({\n  name: \"venn/load\",\n  version: \"0.0.0\",\n  namespace: \"load\",\n  requires: [\"net\"],\n  actions: loadActions,\n  types: { LoadMetrics: LoadMetricsSchema },\n  typeDefs: loadTypeDefs,\n});\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@venn-lang/load",
+  "version": "0.1.0",
+  "description": "The load namespace: describe a load profile, run it, assert on the metrics.",
+  "keywords": [
+    "venn",
+    "testing",
+    "e2e",
+    "load"
+  ],
+  "homepage": "https://github.com/venn-lang/venn/tree/main/packages/std-load#readme",
+  "bugs": "https://github.com/venn-lang/venn/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/venn-lang/venn.git",
+    "directory": "packages/std-load"
+  },
+  "license": "MIT",
+  "author": "Vinicius Borges",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.suite.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@venn-lang/sdk": "0.1.0",
+    "@venn-lang/contracts": "0.1.0",
+    "@venn-lang/types": "0.1.0"
+  },
+  "devDependencies": {
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/actions/constant.ts

@@ -0,0 +1,34 @@
+import {
+  type ActionDefinition,
+  type ActionInput,
+  arg,
+  Duration,
+  defineAction,
+  z,
+} from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { type ConstantProfile, constantProfile } from "../profiles/index.js";
+
+const constantParams = z.object({ over: Duration.optional() });
+
+/**
+ * `load.constant 50 { over: "10s" }`.
+ *
+ * Describes a flat load: `vus` virtual users held steady for `over`. Nothing
+ * runs until the profile is handed to `load.run`.
+ *
+ * @returns a `load.Constant` profile.
+ */
+export const constantAction: ActionDefinition = defineAction({
+  name: "constant",
+  doc: "Build a constant-VUs load profile.",
+  params: constantParams.optional(),
+  args: [arg("vus", t.number, "How many virtual users, held steady.")],
+  result: t.ref("load.Constant"),
+  run: (_ctx, input) => buildConstant(input),
+});
+
+function buildConstant(input: ActionInput<unknown>): ConstantProfile {
+  const params = (input.params ?? {}) as { over?: number };
+  return constantProfile({ vus: Number(input.args[0] ?? 0), over: params.over });
+}

package/src/actions/index.ts

@@ -0,0 +1,8 @@
+import type { ActionDefinition } from "@venn-lang/sdk";
+import { constantAction } from "./constant.js";
+import { rampAction } from "./ramp.js";
+import { runAction } from "./run.js";
+import { spikeAction } from "./spike.js";
+
+/** Every verb in the `load` namespace, in the order the plugin registers them. */
+export const loadActions: ActionDefinition[] = [rampAction, constantAction, spikeAction, runAction];

package/src/actions/ramp.ts

@@ -0,0 +1,45 @@
+import {
+  type ActionDefinition,
+  type ActionInput,
+  arg,
+  Duration,
+  defineAction,
+  z,
+} from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { type RampProfile, rampProfile } from "../profiles/index.js";
+
+const rampParams = z.object({ over: Duration.optional(), hold: Duration.optional() });
+
+/**
+ * `load.ramp 0 200 { over: "30s", hold: "5m" }`.
+ *
+ * Describes a climb from `from` to `to` virtual users across `over`, then held
+ * at `to` for `hold`. Nothing runs until the profile is handed to `load.run`.
+ *
+ * The grammar has no `0 -> 200` arrow sugar, so the two ends are separate
+ * positional arguments. `over` and `hold` accept `"30s"` or a millisecond count.
+ *
+ * @returns a `load.Ramp` profile.
+ */
+export const rampAction: ActionDefinition = defineAction({
+  name: "ramp",
+  doc: "Build a ramp load profile from `from` to `to` VUs.",
+  params: rampParams.optional(),
+  args: [
+    arg("from", t.number, "Virtual users at the start."),
+    arg("to", t.number, "Virtual users at the end."),
+  ],
+  result: t.ref("load.Ramp"),
+  run: (_ctx, input) => buildRamp(input),
+});
+
+function buildRamp(input: ActionInput<unknown>): RampProfile {
+  const params = (input.params ?? {}) as { over?: number; hold?: number };
+  return rampProfile({
+    from: Number(input.args[0] ?? 0),
+    to: Number(input.args[1] ?? 0),
+    over: params.over,
+    hold: params.hold,
+  });
+}

package/src/actions/run.ts

@@ -0,0 +1,25 @@
+import { type ActionDefinition, type ActionInput, arg, defineAction } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import type { LoadProfile } from "../profiles/index.js";
+import { LoadRunnerPort } from "../runner/index.js";
+
+/**
+ * `load.run (load.ramp 0 200 { over: "30s" })`.
+ *
+ * Drives one profile through the `LoadRunner` port. This is the verb that
+ * generates traffic; the builders only describe a shape.
+ *
+ * @returns the `load.Metrics` the run produced.
+ * @throws {VennError} `VN8090` when the host's runner cannot execute a profile.
+ */
+export const runAction: ActionDefinition = defineAction({
+  name: "run",
+  doc: "Run a load profile and return its metrics.",
+  args: [arg("profile", t.ref("load.Profile"), "A profile, as `load.ramp` and friends build.")],
+  result: t.ref("load.Metrics"),
+  run: (ctx, input) => ctx.port(LoadRunnerPort).run(profileOf(input)),
+});
+
+function profileOf(input: ActionInput<unknown>): LoadProfile {
+  return input.args[0] as LoadProfile;
+}

package/src/actions/spike.ts

@@ -0,0 +1,34 @@
+import {
+  type ActionDefinition,
+  type ActionInput,
+  arg,
+  Duration,
+  defineAction,
+  z,
+} from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { type SpikeProfile, spikeProfile } from "../profiles/index.js";
+
+const spikeParams = z.object({ at: Duration.optional() });
+
+/**
+ * `load.spike 500 { at: "5s" }`.
+ *
+ * Describes a single burst to `peak` virtual users, `at` into the run. Nothing
+ * runs until the profile is handed to `load.run`.
+ *
+ * @returns a `load.Spike` profile.
+ */
+export const spikeAction: ActionDefinition = defineAction({
+  name: "spike",
+  doc: "Build a spike load profile that peaks at `peak` VUs.",
+  params: spikeParams.optional(),
+  args: [arg("peak", t.number, "Virtual users at the top of the spike.")],
+  result: t.ref("load.Spike"),
+  run: (_ctx, input) => buildSpike(input),
+});
+
+function buildSpike(input: ActionInput<unknown>): SpikeProfile {
+  const params = (input.params ?? {}) as { at?: number };
+  return spikeProfile({ peak: Number(input.args[0] ?? 0), at: params.at });
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+/**
+ * `@venn-lang/load`: the verbs that describe a load shape (`ramp`, `constant`,
+ * `spike`), the `LoadRunner` port that drives it, and the metrics it yields.
+ */
+
+export * from "./metrics/index.js";
+export { loadPlugin, loadPlugin as default } from "./plugin.js";
+export * from "./profiles/index.js";
+export * from "./runner/index.js";

package/src/metrics/index.ts

@@ -0,0 +1,2 @@
+export { LoadMetricsSchema } from "./load-metrics.schema.js";
+export type { LoadMetrics } from "./load-metrics.types.js";

package/src/metrics/load-metrics.schema.ts

@@ -0,0 +1,12 @@
+import { type ZodType, z } from "@venn-lang/sdk";
+import type { LoadMetrics } from "./load-metrics.types.js";
+
+/** Runtime validator for the nominal `load.Metrics` type. */
+export const LoadMetricsSchema: ZodType<LoadMetrics> = z.object({
+  vus: z.number(),
+  rps: z.number(),
+  p50: z.number(),
+  p95: z.number(),
+  p99: z.number(),
+  errorRate: z.number(),
+});

package/src/metrics/load-metrics.types.ts

@@ -0,0 +1,15 @@
+/**
+ * What a load run reports back. Latencies are in milliseconds and the ordering
+ * `p50 <= p95 <= p99` always holds; the conformance suite enforces it.
+ */
+export interface LoadMetrics {
+  /** Peak concurrent virtual users the run reached. */
+  vus: number;
+  /** Requests per second, averaged over the run. */
+  rps: number;
+  p50: number;
+  p95: number;
+  p99: number;
+  /** Share of failed requests, from 0 to 1. */
+  errorRate: number;
+}

package/src/plugin.ts

@@ -0,0 +1,19 @@
+import { definePlugin, type PluginDefinition } from "@venn-lang/sdk";
+import { loadActions } from "./actions/index.js";
+import { LoadMetricsSchema } from "./metrics/index.js";
+import { loadTypeDefs } from "./types.js";
+
+/**
+ * The `@venn-lang/load` plugin. Registers the `load` namespace: three profile
+ * builders, the `run` verb that executes one, and the profile and metrics
+ * types. Requires the `net` capability, since a run drives real traffic.
+ */
+export const loadPlugin: PluginDefinition = definePlugin({
+  name: "venn/load",
+  version: "0.0.0",
+  namespace: "load",
+  requires: ["net"],
+  actions: loadActions,
+  types: { LoadMetrics: LoadMetricsSchema },
+  typeDefs: loadTypeDefs,
+});

package/src/profiles/build-profiles.ts

@@ -0,0 +1,41 @@
+import type {
+  ConstantProfile,
+  LoadProfile,
+  RampProfile,
+  SpikeProfile,
+} from "./load-profile.types.js";
+
+/**
+ * Builds a ramp profile: a climb from `from` to `to` virtual users across
+ * `over` milliseconds, then held at `to` for `hold` milliseconds.
+ *
+ * @returns the profile. Nothing is executed here.
+ */
+export function rampProfile(args: {
+  from: number;
+  to: number;
+  over?: number;
+  hold?: number;
+}): RampProfile {
+  return { kind: "ramp", from: args.from, to: args.to, over: args.over, hold: args.hold };
+}
+
+/** Builds a flat profile: `vus` virtual users held for `over` milliseconds. */
+export function constantProfile(args: { vus: number; over?: number }): ConstantProfile {
+  return { kind: "constant", vus: args.vus, over: args.over };
+}
+
+/** Builds a burst profile: one spike to `peak` virtual users, `at` ms into the run. */
+export function spikeProfile(args: { peak: number; at?: number }): SpikeProfile {
+  return { kind: "spike", peak: args.peak, at: args.at };
+}
+
+/**
+ * The highest concurrency a profile calls for, whichever shape it is. This is
+ * the number a runner sizes itself against.
+ */
+export function peakVus(profile: LoadProfile): number {
+  if (profile.kind === "ramp") return profile.to;
+  if (profile.kind === "constant") return profile.vus;
+  return profile.peak;
+}

package/src/profiles/index.ts

@@ -0,0 +1,7 @@
+export { constantProfile, peakVus, rampProfile, spikeProfile } from "./build-profiles.js";
+export type {
+  ConstantProfile,
+  LoadProfile,
+  RampProfile,
+  SpikeProfile,
+} from "./load-profile.types.js";

package/src/profiles/load-profile.types.ts

@@ -0,0 +1,25 @@
+/** A ramp from `from` to `to` VUs over `over`, then held for `hold` (ms). */
+export interface RampProfile {
+  kind: "ramp";
+  from: number;
+  to: number;
+  over?: number;
+  hold?: number;
+}
+
+/** A constant `vus` load sustained over `over` (ms). */
+export interface ConstantProfile {
+  kind: "constant";
+  vus: number;
+  over?: number;
+}
+
+/** A single spike to `peak` VUs at `at` (ms into the run). */
+export interface SpikeProfile {
+  kind: "spike";
+  peak: number;
+  at?: number;
+}
+
+/** Whatever a builder produced. `kind` tells the runner which shape it holds. */
+export type LoadProfile = RampProfile | ConstantProfile | SpikeProfile;

package/src/runner/fake-runner.ts

@@ -0,0 +1,20 @@
+import type { LoadMetrics } from "../metrics/index.js";
+import { type LoadProfile, peakVus } from "../profiles/index.js";
+import type { LoadRunner } from "./load-runner.types.js";
+
+/**
+ * The offline `LoadRunner`. Derives plausible metrics from the profile's peak
+ * concurrency and sends no traffic.
+ *
+ * @returns a runner whose results are deterministic for a given profile.
+ */
+export function createFakeLoadRunner(): LoadRunner {
+  return {
+    run: async (profile) => metricsFor(profile),
+  };
+}
+
+function metricsFor(profile: LoadProfile): LoadMetrics {
+  const vus = peakVus(profile);
+  return { vus, rps: vus * 10, p50: 50, p95: 120, p99: 200, errorRate: 0.01 };
+}

package/src/runner/index.ts

@@ -0,0 +1,4 @@
+export { createFakeLoadRunner } from "./fake-runner.js";
+export { LoadRunnerPort } from "./load-runner.port.js";
+export type { LoadRunner } from "./load-runner.types.js";
+export { createRealLoadRunner } from "./real-runner.js";

package/src/runner/load-runner.port.ts

@@ -0,0 +1,13 @@
+import type { Port } from "@venn-lang/contracts";
+import type { LoadRunner } from "./load-runner.types.js";
+
+/**
+ * The port `load.run` drives traffic through. Requires the `net` capability, so
+ * a host without it fails to load the plugin rather than failing mid-run.
+ */
+export const LoadRunnerPort: Port<LoadRunner> = {
+  id: "venn.port.load-runner",
+  version: 1,
+  requires: ["net"],
+  methods: ["run"],
+};

package/src/runner/load-runner.types.ts

@@ -0,0 +1,13 @@
+import type { LoadMetrics } from "../metrics/index.js";
+import type { LoadProfile } from "../profiles/index.js";
+
+/** What turns a profile into traffic. */
+export interface LoadRunner {
+  /**
+   * Executes one profile to completion.
+   *
+   * @returns the metrics observed, with `p50 <= p95 <= p99`.
+   * @throws {VennError} `VN8090` from an implementation that cannot run.
+   */
+  run(profile: LoadProfile): Promise<LoadMetrics>;
+}

package/src/runner/real-runner.ts

@@ -0,0 +1,22 @@
+import { VennError } from "@venn-lang/contracts";
+import type { LoadRunner } from "./load-runner.types.js";
+
+/**
+ * The traffic-generating `LoadRunner`. Not wired up in this build.
+ *
+ * @returns a runner whose `run` throws, so the gap is a legible failure rather
+ * than metrics nobody measured.
+ * @throws {VennError} `VN8090` on every `run`.
+ */
+export function createRealLoadRunner(): LoadRunner {
+  return {
+    run: async () => notImplemented(),
+  };
+}
+
+function notImplemented(): never {
+  throw new VennError({
+    code: "VN8090",
+    message: "The load runner is not implemented in this build.",
+  });
+}

package/src/types.ts

@@ -0,0 +1,38 @@
+import { type TypeSpec, t } from "@venn-lang/types";
+
+/**
+ * The types `@venn-lang/load` publishes to the checker, under the `load` namespace:
+ * the three profiles its builders return, the union `load.run` accepts, and the
+ * metrics it yields. They mirror `profiles/load-profile.types.ts` and
+ * `metrics/load-metrics.types.ts` field by field, dropping the `Load` and
+ * `Profile` affixes the namespace already says: a flow reads `load.Ramp`.
+ *
+ * Durations are `number` here on purpose. The `Duration` schema accepts `"30s"`
+ * or a plain millisecond count, not the language's own `duration` value, and
+ * yields milliseconds. What a profile holds is therefore a count.
+ */
+export const loadTypeDefs: Readonly<Record<string, TypeSpec>> = {
+  /** A ramp from `from` to `to` VUs over `over`, then held for `hold`. */
+  Ramp: t.record(
+    { kind: t.literal("ramp"), from: t.number, to: t.number, over: t.number, hold: t.number },
+    { optional: ["over", "hold"] },
+  ),
+  /** A constant `vus` load sustained over `over`. */
+  Constant: t.record(
+    { kind: t.literal("constant"), vus: t.number, over: t.number },
+    { optional: ["over"] },
+  ),
+  /** A single spike to `peak` VUs at `at` into the run. */
+  Spike: t.record({ kind: t.literal("spike"), peak: t.number, at: t.number }, { optional: ["at"] }),
+  /** Whatever a builder produced. This is what `load.run` takes. */
+  Profile: t.union(t.ref("load.Ramp"), t.ref("load.Constant"), t.ref("load.Spike")),
+  /** What a run yields. The invariant `p50 <= p95 <= p99` always holds. */
+  Metrics: t.record({
+    vus: t.number,
+    rps: t.number,
+    p50: t.number,
+    p95: t.number,
+    p99: t.number,
+    errorRate: t.number,
+  }),
+};