@venn-lang/contracts 0.1.0

package/dist/signal-source.types-BI3TYaCi.d.ts

@@ -0,0 +1,317 @@
+//#region src/ports/clock/clock.types.d.ts
+/** Now, sleeping, deadlines. */
+interface Clock {
+  /** Milliseconds since the epoch, or since the virtual clock's start. */
+  now(): number;
+  sleep(ms: number): Promise<void>;
+}
+/**
+ * A {@link Clock} whose flow of time a test controls.
+ *
+ * `advance` and `setTime` sit outside the negotiated contract, so code holding
+ * a `Clock` can never reach them.
+ */
+interface VirtualClock extends Clock {
+  advance(ms: number): void;
+  setTime(epochMs: number): void;
+}
+//#endregion
+//#region src/ports/file-system/file-system.types.d.ts
+/**
+ * Read and write bytes.
+ *
+ * This is the port that lets `@venn-lang/core` run both in Node (the CLI) and in a
+ * Web Worker (the LSP). A leaked `import fs from "node:fs"` in core would break
+ * the editor, so all byte I/O goes through here.
+ */
+interface FileSystem {
+  /** @throws VennError VN8010 when the path does not exist. */
+  read(path: string): Promise<Uint8Array>;
+  write(path: string, bytes: Uint8Array): Promise<void>;
+  exists(path: string): Promise<boolean>;
+  /** @throws VennError VN8010 when the path does not exist. */
+  remove(path: string): Promise<void>;
+  /**
+   * What a directory holds, one level deep, in no promised order. A path that
+   * is not a directory reads as empty rather than raising: asking what is
+   * inside something that holds nothing has an answer.
+   */
+  list(path: string): Promise<readonly DirEntry[]>;
+}
+/** One name inside a directory, and whether it holds more. */
+interface DirEntry {
+  name: string;
+  directory: boolean;
+}
+//#endregion
+//#region src/ports/lock-provider/lock-provider.types.d.ts
+/** Releases a held lock. Calling it more than once is a no-op. */
+type Release = () => void;
+/** Named mutexes: the semantics behind `@lock` and `@serial`. */
+interface LockProvider {
+  /** Resolves once the lock named `name` is held by this caller alone. */
+  acquire(name: string): Promise<Release>;
+}
+//#endregion
+//#region src/ports/process-provider/process-provider.types.d.ts
+/** What to run, where, and how to hear from it while it runs. */
+interface SpawnArgs {
+  command: string;
+  args?: readonly string[];
+  /** Where it runs. The current directory unless this says otherwise. */
+  cwd?: string;
+  /** Added to the environment the host was started with. */
+  env?: Record<string, string>;
+  /**
+   * Whether to go through the platform shell.
+   *
+   * Needed for a command that is a script rather than an executable: on Windows
+   * `pnpm` is a `.cmd`, and nothing runs it without one. Off by default,
+   * because a shell re-reads the arguments and a quote that meant one thing to
+   * the caller means another to `cmd.exe`. Only the caller knows which of the
+   * two it is holding.
+   */
+  shell?: boolean;
+  /**
+   * Called with each chunk the command writes, as it writes it.
+   *
+   * A package manager installing a hundred packages takes half a minute, and a
+   * command silent for half a minute reads as one that has hung. What is
+   * streamed here is kept as well, so a caller can show it and read it after.
+   */
+  onOutput?: (chunk: string) => void;
+}
+/** How a run ended. */
+interface ProcessResult {
+  code: number;
+  /** Everything it wrote, stdout and stderr together, in the order written. */
+  output: string;
+}
+/** A spawned subprocess. */
+interface ProcessHandle {
+  readonly pid: number;
+  /** Resolves when the command ends. Never rejects: a failure is a result. */
+  wait(): Promise<ProcessResult>;
+  kill(): void;
+}
+/** Spawn subprocesses: a package manager, a driver, anything the host allows. */
+interface ProcessProvider {
+  spawn(args: SpawnArgs): ProcessHandle;
+}
+//#endregion
+//#region src/ports/random/random.types.d.ts
+/**
+ * A source of randomness. Every implementation is reproducible, so a failing
+ * run can be replayed.
+ */
+interface Random {
+  /** Uniform float in [0, 1). */
+  next(): number;
+  /** Uniform integer in the inclusive range [min, max]. */
+  int(min: number, max: number): number;
+}
+//#endregion
+//#region src/ports/secret-provider/secret-provider.types.d.ts
+/**
+ * A value that redacts itself. Serialising one, by any route, yields the
+ * redaction marker: redaction happens at the producer, because redacting in the
+ * UI is already too late.
+ */
+interface Secret {
+  /** The only way to the raw value, and deliberately something you must ask for. */
+  reveal(): string;
+  toString(): string;
+  toJSON(): string;
+}
+/** Resolves `secrets.*` names to redaction-marked values. */
+interface SecretProvider {
+  get(name: string): Secret | undefined;
+  has(name: string): boolean;
+}
+//#endregion
+//#region src/conformance/harness.types.d.ts
+/**
+ * Builds a fresh implementation for a single conformance run.
+ *
+ * Called once per test rather than once per suite, so no test can observe state
+ * another test left behind.
+ */
+type PortFactory<T> = () => T | Promise<T>;
+/** One implementation under test. */
+interface ConformanceSpec<T> {
+  /** Shown in the test name, e.g. "memory" or "node". */
+  readonly name: string;
+  readonly factory: PortFactory<T>;
+}
+//#endregion
+//#region src/ports/secret-provider/secret-provider.suite.d.ts
+/** A secret the implementation under test is known to hold. */
+type KnownSecret = {
+  name: string;
+  raw: string;
+};
+/**
+ * The {@link SecretProvider} TCK. The redaction law is the load-bearing one:
+ * an implementation that leaks through `JSON.stringify` fails here.
+ */
+declare function secretProviderConformance(spec: ConformanceSpec<SecretProvider> & {
+  known: KnownSecret;
+}): void;
+//#endregion
+//#region src/ports/manifest-provider/project.types.d.ts
+/**
+ * What a manifest declares about the project itself, as against how it runs.
+ *
+ * The shape follows Cargo's, because the questions are the same and an answer
+ * the reader already knows beats a better one they must learn. Where Cargo has
+ * something this does not, the gap is noted so it reads as a decision.
+ */
+/** `[package]`: who this is. */
+interface PackageInfo {
+  name: string;
+  /**
+   * What `[package] version` said, and nothing when it said nothing.
+   *
+   * Optional so "not written" stays distinguishable from "written as 0.0.0": a
+   * workspace member inherits the first and keeps the second. `Manifest.version`
+   * is the resolved value, with the default already applied.
+   */
+  version?: string;
+  description?: string;
+  license?: string;
+  authors: readonly string[];
+  /** `[package] edition`: which language revision this was written against. */
+  edition?: string;
+}
+/** What a project builds. A server is a `bin` that does not end. */
+type TargetKind = "lib" | "bin" | "test";
+/** `[lib]` or one entry of `[[bin]]`: a thing to build, and where it starts. */
+interface BuildTarget {
+  kind: TargetKind;
+  /** The name it is known by; a `bin`'s name is what `venn run --bin` takes. */
+  name: string;
+  /** The `.vn` file this target starts from, relative to the manifest. */
+  path: string;
+}
+/** One entry of `[dependencies]` / `[dev-dependencies]`. */
+interface Dependency {
+  name: string;
+  /** A semver range, or absent when the version comes from elsewhere. */
+  version?: string;
+  /** `{ path = "../other" }`: a sibling in this workspace or on disk. */
+  path?: string;
+  /** `{ workspace = true }`: take the version the workspace pinned. */
+  fromWorkspace: boolean;
+  /** `{ optional = true }`: resolved and locked, installed only on demand. */
+  optional: boolean;
+}
+/**
+ * `[profile.dev]` and `[profile.release]`: how a build is made.
+ *
+ * One key, because one key is what a build does today. Settings about generated
+ * code, such as `sourceMap` and `minify`, arrive with the compiler: declaring
+ * them now would read as a contract and honour nothing.
+ */
+interface Profile {
+  /** Whether a problem stops the build instead of only being reported. */
+  strict?: boolean;
+}
+/**
+ * Which package manager runs underneath `venn add` and `venn remove`.
+ *
+ * The interface is ours, the resolution is not: resolving versions well is
+ * years of work against three moving targets.
+ */
+type PackageManagerName = "pnpm" | "npm" | "bun" | "yarn";
+/** The `[tooling]` table. */
+interface ToolingSettings {
+  manager: PackageManagerName;
+}
+/**
+ * `[workspace]`: a root that owns members, one lockfile and one `target/`.
+ *
+ * `[features]` is deliberately absent. It is the most intricate part of Cargo,
+ * it rests on conditional compilation this language does not have, and half of
+ * it would be worse than none.
+ */
+interface WorkspaceSettings {
+  /** Path globs naming the members, e.g. `["packages/*"]`. */
+  members: readonly string[];
+  exclude: readonly string[];
+  /** Which members a command with no target acts on. Empty means all of them. */
+  defaultMembers: readonly string[];
+  /** `[workspace.package]`: metadata a member may inherit. */
+  package: Partial<PackageInfo>;
+  /** `[workspace.dependencies]`: the versions `{ workspace = true }` takes. */
+  dependencies: readonly Dependency[];
+}
+//#endregion
+//#region src/ports/manifest-provider/manifest.types.d.ts
+/** A parsed `venn.toml`: the project manifest the LSP and the runner read. */
+interface Manifest {
+  name: string;
+  version: string;
+  /** `[package]` in full. `name` and `version` above are the short way in. */
+  package: PackageInfo;
+  /** `[lib]` and `[[bin]]`, in the order they were written. */
+  targets: readonly BuildTarget[];
+  dependencies: readonly Dependency[];
+  devDependencies: readonly Dependency[];
+  /** `[patch]`: a version this project insists on, wherever it is asked for. */
+  patch: readonly Dependency[];
+  /** `[profile.<name>]`, keyed by name. `dev` and `release` are built in. */
+  profiles: Record<string, Profile>;
+  tooling: ToolingSettings;
+  /** `[workspace]`, or absent when this manifest is a plain package. */
+  workspace?: WorkspaceSettings;
+  /** `[env.<name>]` sections, mapping an environment to its variables. */
+  env: Record<string, Record<string, string>>;
+  /**
+   * `[env] files`: which dotenv files to read, in order, later winning.
+   * `${name}` stands for the selected environment. Empty means the convention.
+   */
+  envFiles: readonly string[];
+  /** `[paths]`, mapping an `#alias` to a directory. */
+  paths: Record<string, string>;
+  /** `[format]`: how `venn fmt` and the editor format this project. */
+  format: FormatSettings;
+}
+/** The `[format]` table. Absent keys fall back to the language defaults. */
+interface FormatSettings {
+  indent?: number;
+  tabs?: boolean;
+  organize?: boolean;
+  sort?: boolean;
+}
+/**
+ * Produces a {@link Manifest}. Implementations: `toml-manifest` parses one,
+ * `memory-manifest` returns a preset.
+ */
+interface ManifestProvider {
+  load(): Manifest;
+}
+//#endregion
+//#region src/ports/signal-source/signal-source.types.d.ts
+/**
+ * The ways a system asks a program to stop. `SIGBREAK` is Windows' Ctrl+Break,
+ * `SIGHUP` is the terminal itself going away.
+ */
+declare const ALL_SIGNALS: readonly ["SIGINT", "SIGTERM", "SIGBREAK", "SIGHUP"];
+/** One signal name, drawn from {@link ALL_SIGNALS}. */
+type SystemSignal = (typeof ALL_SIGNALS)[number];
+/** Called on every delivery of the signal it was registered for. */
+type SignalHandler = (signal: SystemSignal) => void;
+/** Drops a subscription. Calling it more than once is harmless. */
+type Unsubscribe = () => void;
+/**
+ * Where a program hears the system asking it to stop.
+ *
+ * The double matters more than usual here: raising a true SIGINT inside a test
+ * run stops the test runner, not the code under test.
+ */
+interface SignalSource {
+  on(signal: SystemSignal, handler: SignalHandler): Unsubscribe;
+}
+//#endregion
+export { DirEntry as A, Random as C, SpawnArgs as D, ProcessResult as E, Clock as M, VirtualClock as N, LockProvider as O, SecretProvider as S, ProcessProvider as T, KnownSecret as _, Unsubscribe as a, PortFactory as b, ManifestProvider as c, PackageInfo as d, PackageManagerName as f, WorkspaceSettings as g, ToolingSettings as h, SystemSignal as i, FileSystem as j, Release as k, BuildTarget as l, TargetKind as m, SignalHandler as n, FormatSettings as o, Profile as p, SignalSource as r, Manifest as s, ALL_SIGNALS as t, Dependency as u, secretProviderConformance as v, ProcessHandle as w, Secret as x, ConformanceSpec as y };
+//# sourceMappingURL=signal-source.types-BI3TYaCi.d.ts.map

package/dist/signal-source.types-BI3TYaCi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signal-source.types-BI3TYaCi.d.ts","names":[],"sources":["../src/ports/clock/clock.types.ts","../src/ports/file-system/file-system.types.ts","../src/ports/lock-provider/lock-provider.types.ts","../src/ports/process-provider/process-provider.types.ts","../src/ports/random/random.types.ts","../src/ports/secret-provider/secret-provider.types.ts","../src/conformance/harness.types.ts","../src/ports/secret-provider/secret-provider.suite.ts","../src/ports/manifest-provider/project.types.ts","../src/ports/manifest-provider/manifest.types.ts","../src/ports/signal-source/signal-source.types.ts"],"mappings":";;UACiB;;EAEf;EACA,MAAM,aAAa;;;;;;;;UASJ,qBAAqB;EACpC,QAAQ;EACR,QAAQ;;;;;;;;;;;UCRO;;EAEf,KAAK,eAAe,QAAQ;EAC5B,MAAM,cAAc,OAAO,aAAa;EACxC,OAAO,eAAe;;EAEtB,OAAO,eAAe;;;;;;EAMtB,KAAK,eAAe,iBAAiB;;;UAItB;EACf;EACA;;;;;KCxBU;;UAGK;;EAEf,QAAQ,eAAe,QAAQ;;;;;UCLhB;EACf;EACA;;EAEA;;EAEA,MAAM;;;;;;;;;;EAUN;;;;;;;;EAQA,YAAY;;;UAIG;EACf;;EAEA;;;UAIe;WACN;;EAET,QAAQ,QAAQ;EAChB;;;UAIe;EACf,MAAM,MAAM,YAAY;;;;;;;;UCzCT;;EAEf;;EAEA,IAAI,aAAa;;;;;;;;;UCHF;;EAEf;EACA;EACA;;;UAIe;EACf,IAAI,eAAe;EACnB,IAAI;;;;;;;;;;KCTM,YAAY,WAAW,IAAI,QAAQ;;UAG9B,gBAAgB;;WAEtB;WACA,SAAS,YAAY;;;;;KCPpB;EAAgB;EAAc;;;;;;iBAM1B,0BACd,MAAM,gBAAgB;EAAoB,OAAO;;;;;;;;;;;;UCHlC;EACf;;;;;;;;EAQA;EACA;EACA;EACA;;EAEA;;;KAIU;;UAGK;EACf,MAAM;;EAEN;;EAEA;;;UAIe;EACf;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;;;UAUe;;EAEf;;;;;;;;KASU;;UAGK;EACf,SAAS;;;;;;;;;UAUM;;EAEf;EACA;;EAEA;;EAEA,SAAS,QAAQ;;EAEjB,uBAAuB;;;;;UClFR;EACf;EACA;;EAEA,SAAS;;EAET,kBAAkB;EAClB,uBAAuB;EACvB,0BAA0B;;EAE1B,gBAAgB;;EAEhB,UAAU,eAAe;EACzB,SAAS;;EAET,YAAY;;EAEZ,KAAK,eAAe;;;;;EAKpB;;EAEA,OAAO;;EAEP,QAAQ;;;UAIO;EACf;EACA;EACA;EACA;;;;;;UAOe;EACf,QAAQ;;;;;;;;cChDG;;KAGD,uBAAuB;;KAGvB,iBAAiB,QAAQ;;KAGzB;;;;;;;UAQK;EACf,GAAG,QAAQ,cAAc,SAAS,gBAAgB"}

package/dist/testing.d.ts

@@ -0,0 +1,84 @@
+import { C as Random, D as SpawnArgs, M as Clock, O as LockProvider, T as ProcessProvider, b as PortFactory, c as ManifestProvider, i as SystemSignal, j as FileSystem, r as SignalSource, v as secretProviderConformance, y as ConformanceSpec } from "./signal-source.types-BI3TYaCi.js";
+//#region src/conformance/expect-venn-error.d.ts
+/**
+ * Asserts that an async operation rejects with a `VennError` whose `.code`
+ * matches.
+ *
+ * Suites assert on the code and never on the message, so wording can be
+ * improved without breaking a conformance run.
+ *
+ * @param args.op - the operation expected to reject.
+ * @param args.code - pattern the error code must match, e.g. `/^VN8/`.
+ */
+declare function expectVennError(args: {
+  op: () => Promise<unknown>;
+  code: RegExp;
+}): Promise<void>;
+//#endregion
+//#region src/ports/clock/clock.suite.d.ts
+/** The {@link Clock} TCK. Both the system and virtual clocks satisfy it. */
+declare function clockConformance(spec: ConformanceSpec<Clock>): void;
+//#endregion
+//#region src/ports/file-system/file-system.suite.d.ts
+/** The {@link FileSystem} TCK. Real and double both run it. */
+declare function fileSystemConformance(spec: ConformanceSpec<FileSystem>): void;
+//#endregion
+//#region src/ports/lock-provider/lock-provider.suite.d.ts
+/**
+ * The {@link LockProvider} TCK. Acquiring, releasing and acquiring again must
+ * not deadlock, which is the one law the fake and the real mutex share.
+ */
+declare function lockProviderConformance(spec: ConformanceSpec<LockProvider>): void;
+//#endregion
+//#region src/ports/manifest-provider/manifest.suite.d.ts
+/**
+ * The {@link ManifestProvider} TCK. Whatever the source, `load()` returns a
+ * manifest with a name and an env map, never a partial one.
+ */
+declare function manifestProviderConformance(spec: ConformanceSpec<ManifestProvider> & {
+  expectedName: string;
+}): void;
+//#endregion
+//#region src/ports/process-provider/process-provider.suite.d.ts
+/**
+ * The {@link ProcessProvider} TCK.
+ *
+ * Each implementation is asked to run something that says a known thing and
+ * ends with a known code. *What* it is asked to run differs, since a fake has
+ * no shell and the real one has no script, but the answer must not.
+ */
+declare function processProviderConformance(spec: ConformanceSpec<ProcessProvider> & {
+  runs: SpawnArgs;
+  expected: {
+    code: number;
+    output: string;
+  };
+}): void;
+//#endregion
+//#region src/ports/random/random.suite.d.ts
+/** The {@link Random} TCK: the range laws both seeded and fixed satisfy. */
+declare function randomConformance(spec: ConformanceSpec<Random>): void;
+//#endregion
+//#region src/ports/signal-source/signal-source.suite.d.ts
+/** How a suite delivers a signal to the implementation it is testing. */
+interface SignalSpec {
+  name: string;
+  factory(): SignalSource;
+  /** Deliver `signal` the way this implementation really receives one. */
+  raise(args: {
+    source: SignalSource;
+    signal: SystemSignal;
+  }): void;
+  /** The signal this implementation can be asked to deliver here. */
+  delivers: SystemSignal;
+  /** A second signal, subscribed to but never raised, to prove they stay apart. */
+  other: SystemSignal;
+}
+/**
+ * The {@link SignalSource} TCK. The process and the fake both run it, because a
+ * double that delivers differently is a test that lies about shutdown.
+ */
+declare function signalSourceConformance(spec: SignalSpec): void;
+//#endregion
+export { type ConformanceSpec, type PortFactory, type SignalSpec, clockConformance, expectVennError, fileSystemConformance, lockProviderConformance, manifestProviderConformance, processProviderConformance, randomConformance, secretProviderConformance, signalSourceConformance };
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","names":[],"sources":["../src/conformance/expect-venn-error.ts","../src/ports/clock/clock.suite.ts","../src/ports/file-system/file-system.suite.ts","../src/ports/lock-provider/lock-provider.suite.ts","../src/ports/manifest-provider/manifest.suite.ts","../src/ports/process-provider/process-provider.suite.ts","../src/ports/random/random.suite.ts","../src/ports/signal-source/signal-source.suite.ts"],"mappings":";;;;;;;;;;;;iBAYsB,gBAAgB;EACpC,UAAU;EACV,MAAM;IACJ;;;;iBCVY,iBAAiB,MAAM,gBAAgB;;;;iBCCvC,sBAAsB,MAAM,gBAAgB;;;;;;;iBCE5C,wBAAwB,MAAM,gBAAgB;;;;;;;iBCA9C,4BACd,MAAM,gBAAgB;EAAsB;;;;;;;;;;;iBCE9B,2BACd,MAAM,gBAAgB;EACpB,MAAM;EACN;IAAY;IAAc;;;;;;iBCTd,kBAAkB,MAAM,gBAAgB;;;;UCDvC;EACf;EACA,WAAW;;EAEX,MAAM;IAAQ,QAAQ;IAAc,QAAQ;;;EAE5C,UAAU;;EAEV,OAAO;;;;;;iBAOO,wBAAwB,MAAM"}

package/dist/testing.js

@@ -0,0 +1,276 @@
+import { describe, expect, it } from "vitest";
+import { fc, test } from "@fast-check/vitest";
+//#region src/conformance/expect-venn-error.ts
+/**
+* Asserts that an async operation rejects with a `VennError` whose `.code`
+* matches.
+*
+* Suites assert on the code and never on the message, so wording can be
+* improved without breaking a conformance run.
+*
+* @param args.op - the operation expected to reject.
+* @param args.code - pattern the error code must match, e.g. `/^VN8/`.
+*/
+async function expectVennError(args) {
+	await expect(args.op()).rejects.toMatchObject({ code: expect.stringMatching(args.code) });
+}
+//#endregion
+//#region src/ports/clock/clock.suite.ts
+/** The {@link Clock} TCK. Both the system and virtual clocks satisfy it. */
+function clockConformance(spec) {
+	describe(`Clock · ${spec.name}`, () => {
+		it("now() is non-decreasing", async () => {
+			const clock = await spec.factory();
+			const first = clock.now();
+			expect(clock.now()).toBeGreaterThanOrEqual(first);
+		});
+		it("sleep advances now() by about the requested delay", async () => {
+			const clock = await spec.factory();
+			const before = clock.now();
+			await clock.sleep(20);
+			expect(clock.now()).toBeGreaterThanOrEqual(before + 18);
+		});
+	});
+}
+//#endregion
+//#region src/ports/file-system/file-system.suite.ts
+/** The {@link FileSystem} TCK. Real and double both run it. */
+function fileSystemConformance(spec) {
+	describe(`FileSystem · ${spec.name}`, () => {
+		it("read returns exactly the bytes written", async () => {
+			const fs = await spec.factory();
+			const bytes = new Uint8Array([
+				1,
+				2,
+				3,
+				4
+			]);
+			await fs.write("a.bin", bytes);
+			expect(await fs.read("a.bin")).toEqual(bytes);
+		});
+		it("reading a missing path fails with VN8, never a raw error", async () => {
+			const fs = await spec.factory();
+			await expectVennError({
+				op: () => fs.read("missing.bin"),
+				code: /^VN8/
+			});
+		});
+		it("exists reflects write then remove", async () => {
+			const fs = await spec.factory();
+			await fs.write("k.bin", new Uint8Array([0]));
+			expect(await fs.exists("k.bin")).toBe(true);
+			await fs.remove("k.bin");
+			expect(await fs.exists("k.bin")).toBe(false);
+		});
+		/**
+		* Bounded in both draws and payload, because `node-fs` runs this against a
+		* real disk. Twenty-five draws demonstrate last-write-wins as well as
+		* fast-check's default hundred, and the raised timeout means a loaded
+		* machine reports a slow disk rather than a failure.
+		*/
+		test.prop([fc.uint8Array({ maxLength: 4096 })], { numRuns: 25 })("write is last-write-wins", async (bytes) => {
+			const fs = await spec.factory();
+			await fs.write("k.bin", new Uint8Array([9]));
+			await fs.write("k.bin", bytes);
+			expect(await fs.read("k.bin")).toEqual(bytes);
+		}, 2e4);
+		/**
+		* A workspace's `members = ["packages/*"]` rests on listing, so the two
+		* implementations have to agree about it. The double has no directories at
+		* all, only paths, which is exactly why this is asked of both.
+		*/
+		it("lists what a directory holds, one level deep", async () => {
+			const fs = await spec.factory();
+			await fs.write("pkg/a/venn.toml", new Uint8Array([1]));
+			await fs.write("pkg/b/venn.toml", new Uint8Array([1]));
+			await fs.write("pkg/top.txt", new Uint8Array([1]));
+			expect((await fs.list("pkg")).map((entry) => entry.name).sort()).toEqual([
+				"a",
+				"b",
+				"top.txt"
+			]);
+		});
+		it("says which of them hold more", async () => {
+			const fs = await spec.factory();
+			await fs.write("root/inside/deep.txt", new Uint8Array([1]));
+			await fs.write("root/flat.txt", new Uint8Array([1]));
+			const found = await fs.list("root");
+			expect(found.find((entry) => entry.name === "inside")?.directory).toBe(true);
+			expect(found.find((entry) => entry.name === "flat.txt")?.directory).toBe(false);
+		});
+		/** Asking what is inside something that holds nothing has an answer. */
+		it("reads a path that is not a directory as empty", async () => {
+			expect(await (await spec.factory()).list("nao/existe")).toEqual([]);
+		});
+	});
+}
+//#endregion
+//#region src/ports/lock-provider/lock-provider.suite.ts
+/**
+* The {@link LockProvider} TCK. Acquiring, releasing and acquiring again must
+* not deadlock, which is the one law the fake and the real mutex share.
+*/
+function lockProviderConformance(spec) {
+	describe(`LockProvider · ${spec.name}`, () => {
+		it("acquire returns a release, and re-acquiring after release works", async () => {
+			const lock = await spec.factory();
+			(await lock.acquire("k"))();
+			const again = await lock.acquire("k");
+			again();
+			expect(typeof again).toBe("function");
+		});
+	});
+}
+//#endregion
+//#region src/ports/manifest-provider/manifest.suite.ts
+/**
+* The {@link ManifestProvider} TCK. Whatever the source, `load()` returns a
+* manifest with a name and an env map, never a partial one.
+*/
+function manifestProviderConformance(spec) {
+	describe(`ManifestProvider · ${spec.name}`, () => {
+		it("loads a manifest with a name and env map", async () => {
+			const manifest = (await spec.factory()).load();
+			expect(manifest.name).toBe(spec.expectedName);
+			expect(typeof manifest.env).toBe("object");
+		});
+	});
+}
+//#endregion
+//#region src/ports/process-provider/process-provider.suite.ts
+/**
+* The {@link ProcessProvider} TCK.
+*
+* Each implementation is asked to run something that says a known thing and
+* ends with a known code. *What* it is asked to run differs, since a fake has
+* no shell and the real one has no script, but the answer must not.
+*/
+function processProviderConformance(spec) {
+	describe(`ProcessProvider · ${spec.name}`, () => {
+		it("waits for the command and reports how it ended", async () => {
+			const result = await (await spec.factory()).spawn(spec.runs).wait();
+			expect(result.code).toBe(spec.expected.code);
+			expect(result.output).toContain(spec.expected.output);
+		});
+		/** Half a minute of silence reads as a command that has hung. */
+		it("streams what the command writes, as it writes it", async () => {
+			const proc = await spec.factory();
+			const seen = [];
+			await proc.spawn({
+				...spec.runs,
+				onOutput: (chunk) => seen.push(chunk)
+			}).wait();
+			expect(seen.join("")).toContain(spec.expected.output);
+		});
+		it("hands back a handle that can be asked to stop", async () => {
+			const handle = (await spec.factory()).spawn(spec.runs);
+			expect(typeof handle.pid).toBe("number");
+			expect(() => handle.kill()).not.toThrow();
+		});
+	});
+}
+//#endregion
+//#region src/ports/random/random.suite.ts
+/** The {@link Random} TCK: the range laws both seeded and fixed satisfy. */
+function randomConformance(spec) {
+	describe(`Random · ${spec.name}`, () => {
+		it("next() stays within [0, 1)", async () => {
+			const random = await spec.factory();
+			for (let i = 0; i < 100; i++) {
+				const value = random.next();
+				expect(value).toBeGreaterThanOrEqual(0);
+				expect(value).toBeLessThan(1);
+			}
+		});
+		it("int(min, max) stays within the inclusive range", async () => {
+			const random = await spec.factory();
+			for (let i = 0; i < 100; i++) {
+				const value = random.int(3, 7);
+				expect(value).toBeGreaterThanOrEqual(3);
+				expect(value).toBeLessThanOrEqual(7);
+			}
+		});
+	});
+}
+//#endregion
+//#region src/ports/secret-provider/secret-provider.suite.ts
+/**
+* The {@link SecretProvider} TCK. The redaction law is the load-bearing one:
+* an implementation that leaks through `JSON.stringify` fails here.
+*/
+function secretProviderConformance(spec) {
+	describe(`SecretProvider · ${spec.name}`, () => {
+		it("reveals the known secret", async () => {
+			expect((await spec.factory()).get(spec.known.name)?.reveal()).toBe(spec.known.raw);
+		});
+		it("never leaks the raw value through serialization", async () => {
+			const secret = (await spec.factory()).get(spec.known.name);
+			expect(JSON.stringify(secret)).not.toContain(spec.known.raw);
+			expect(String(secret)).not.toContain(spec.known.raw);
+		});
+	});
+}
+//#endregion
+//#region src/ports/signal-source/signal-source.suite.ts
+/**
+* The {@link SignalSource} TCK. The process and the fake both run it, because a
+* double that delivers differently is a test that lies about shutdown.
+*/
+function signalSourceConformance(spec) {
+	describe(`SignalSource · ${spec.name}`, () => {
+		const listen = () => {
+			const source = spec.factory();
+			return {
+				source,
+				seen: [],
+				raise: () => spec.raise({
+					source,
+					signal: spec.delivers
+				})
+			};
+		};
+		it("calls the handler with the signal that arrived", () => {
+			const { source, seen, raise } = listen();
+			const off = source.on(spec.delivers, (signal) => seen.push(signal));
+			raise();
+			off();
+			expect(seen).toEqual([spec.delivers]);
+		});
+		it("calls every handler waiting on that signal", () => {
+			const { source, seen, raise } = listen();
+			const first = source.on(spec.delivers, () => seen.push(spec.delivers));
+			const second = source.on(spec.delivers, () => seen.push(spec.delivers));
+			raise();
+			first();
+			second();
+			expect(seen).toHaveLength(2);
+		});
+		it("leaves other signals alone", () => {
+			const { source, seen, raise } = listen();
+			const off = source.on(spec.other, (signal) => seen.push(signal));
+			raise();
+			off();
+			expect(seen).toEqual([]);
+		});
+		it("stops delivering once unsubscribed, and unsubscribing twice is harmless", () => {
+			const { source, seen, raise } = listen();
+			const off = source.on(spec.delivers, (signal) => seen.push(signal));
+			off();
+			off();
+			raise();
+			expect(seen).toEqual([]);
+		});
+		it("keeps delivering while the subscription lives", () => {
+			const { source, seen, raise } = listen();
+			const off = source.on(spec.delivers, (signal) => seen.push(signal));
+			raise();
+			raise();
+			off();
+			expect(seen).toEqual([spec.delivers, spec.delivers]);
+		});
+	});
+}
+//#endregion
+export { clockConformance, expectVennError, fileSystemConformance, lockProviderConformance, manifestProviderConformance, processProviderConformance, randomConformance, secretProviderConformance, signalSourceConformance };
+
+//# sourceMappingURL=testing.js.map