From 60f4c9ad71fc351feb058c90fad7a9705a1ba4d4 Mon Sep 17 00:00:00 2001 From: Richard Nienaber Date: Tue, 8 Sep 2026 08:04:43 +0100 Subject: [PATCH] seed and tape Java and .NET ports Both languages compile on the way to running, which is what a runner can join: neither has an environment variable that puts a different generator behind the one a program calls. Java ships a javaagent that rewrites the port's own call sites as each class loads -- Math.random, Random and ThreadLocalRandom become calls to a shim that returns the next tape value. Written against java.lang.classfile, standard since JDK 24, so the agent carries no bytecode library; it rewrites the port and leaves the JDK alone, so nothing is retransformed and no platform class is patched. It is the one shim that has to be built, which is what `make shims` is for. .NET declares a System.Random of its own and hands it to the compiler ahead of the real one, injected with an MSBuild targets file that reaches a single .cs file as readily as a .csproj. Replacing the class replaces Shuffle, GetItems and Random.Shared along with the draws, which makes it the widest of the shims. DOTNET_STARTUP_HOOKS was the obvious route and is a dead end: file-based apps build with startup hooks and dynamic code both switched off, so a detour library has nothing to detour with. The image grows a Temurin JDK and a .NET SDK, both pinned and checksummed like everything else in it, and the CI matrix installs the same two. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_019f9gkZVUEo3jtv51GSb4vJ --- .github/workflows/ci.yaml | 20 ++ .gitignore | 6 + Makefile | 19 +- README.md | 4 +- docker/Dockerfile | 51 +++- docker/run.sh | 13 + docs/container.md | 5 +- docs/determinism.md | 71 ++++-- internal/play/runner_integration_test.go | 84 ++++++- runners/dotnet.yaml | 49 ++++ runners/dotnet/prescript.targets | 23 ++ runners/dotnet/prescript/Random.cs | 306 +++++++++++++++++++++++ runners/java.yaml | 34 +++ runners/java/manifest.txt | 2 + runners/java/prescript/Agent.java | 176 +++++++++++++ runners/java/prescript/Tape.java | 183 ++++++++++++++ test/fixtures/rng/rng.cs | 20 ++ test/fixtures/rng/rng.java | 34 +++ 18 files changed, 1071 insertions(+), 29 deletions(-) create mode 100644 runners/dotnet.yaml create mode 100644 runners/dotnet/prescript.targets create mode 100644 runners/dotnet/prescript/Random.cs create mode 100644 runners/java.yaml create mode 100644 runners/java/manifest.txt create mode 100644 runners/java/prescript/Agent.java create mode 100644 runners/java/prescript/Tape.java create mode 100644 test/fixtures/rng/rng.cs create mode 100644 test/fixtures/rng/rng.java diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 1bd8b35..1273af2 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -29,6 +29,26 @@ jobs: with: go-version: ${{ matrix.go-version }} + # The runner image ships older versions of both. Java 25 to match the + # container and to clear the agent's floor of 24, where + # java.lang.classfile became standard; .NET 10 because a port is a single + # .cs file and `dotnet run` only accepts one from 10 onwards. + - name: setup java + uses: actions/setup-java@v5 + with: + distribution: temurin + java-version: '25' + + - name: setup dotnet + uses: actions/setup-dotnet@v5 + with: + dotnet-version: '10.0.x' + + # The Java shim is a jar, so unlike every other runner's it has to exist + # before the suite can use it. + - name: make shims + run: make shims + - name: make test # Every language the shipped runners seed is present on this image, so # a runner test that skips here is a runner nobody is checking. This diff --git a/.gitignore b/.gitignore index 4b1589a..ac15541 100644 --- a/.gitignore +++ b/.gitignore @@ -17,6 +17,12 @@ # CPython writes this next to the seeding shim the moment a runner uses it. __pycache__/ +# The Java shim is built by `make shims` rather than checked in: a jar is a +# binary, and one built from sources in this repository is easier to trust than +# one that arrived with it. +runners/java/classes/ +runners/java/prescript-agent.jar + # other TODO.md tmp/ diff --git a/Makefile b/Makefile index 2c7ad11..cc5ee6c 100644 --- a/Makefile +++ b/Makefile @@ -7,7 +7,7 @@ VINTBAS_ASSET := vintbas-$(shell uname -s | tr '[:upper:]' '[:lower:]')-$(shell VINTBAS_URL := https://github.com/rjnienaber/prescript/releases/download/$(VINTBAS_RELEASE)/$(VINTBAS_ASSET) .PHONY: dependencies -dependencies: tools vintbas +dependencies: tools vintbas shims # Build/lint tooling only. Kept separate from `vintbas` so CI can install # what it needs without depending on an external download. @@ -26,6 +26,21 @@ vintbas: curl -fsSL $(VINTBAS_URL) -o ${HOME}/.local/bin/vintbas chmod +x ${HOME}/.local/bin/vintbas +# The one runner shim that has to be compiled. Ruby, Python, Node and .NET all +# ship theirs as source the interpreter or the compiler reads on its way past; +# a JVM agent is a jar or it is nothing. +# +# --release 24 rather than whatever JDK is to hand, because the jar is built on +# a developer's machine and run in the container: 24 is where java.lang.classfile +# became standard, and is therefore both the floor the agent needs and the +# oldest JVM the jar should refuse to run on. +.PHONY: shims +shims: + javac --release 24 -Xlint:all -d runners/java/classes \ + runners/java/prescript/Tape.java runners/java/prescript/Agent.java + jar --create --file runners/java/prescript-agent.jar \ + --manifest runners/java/manifest.txt -C runners/java/classes . + # Re-records the tape of random values from the reference interpreter. Not # wired into any other target on purpose: the tape is checked in because a # recorded sequence is only useful when every port replays the same one, and @@ -73,7 +88,7 @@ docker_shell: # environment, and pinning a linter into the image would mean rebuilding it to # upgrade one. .PHONY: container_checks -container_checks: test build_dev examples +container_checks: shims test build_dev examples .PHONY: format format: diff --git a/README.md b/README.md index 61061ca..6417051 100644 --- a/README.md +++ b/README.md @@ -201,7 +201,9 @@ testable: prescript play scripts/33-dice.yaml --runner runners/ruby.yaml -- 33_Dice/ruby/dice.rb ``` -Ruby, Python, Node and Go ship and are covered by tests. +Ruby, Python, Node, Java and .NET ship and take a tape; Go ships and can be +seeded but not taped. All are covered by tests. The Java shim is a javaagent +jar, so it has to be built once with `make shims` before its runner will work. A seed makes one port repeatable, but the same seed gives each language a different sequence, so one script still cannot serve them all. `--tape` closes diff --git a/docker/Dockerfile b/docker/Dockerfile index 3eb9e04..82e8bcf 100644 --- a/docker/Dockerfile +++ b/docker/Dockerfile @@ -22,13 +22,24 @@ ARG BASE_DIGEST # Ruby and Python come from Debian stable, which is what pinning means for a # distribution: a fixed series that takes security fixes and no new features -# for the life of the release. Go, Node and the reference interpreter are not -# in it, so they are fetched from upstream and checked against a published -# checksum before anything is unpacked. +# for the life of the release. Go, Node, Java, .NET and the reference +# interpreter are not in it, so they are fetched from upstream and checked +# against a published checksum before anything is unpacked. ARG GO_VERSION=1.24.13 ARG GO_SHA256=1fc94b57134d51669c72173ad5d49fd62afb0f1db9bf3f798fd98ee423f8d730 ARG NODE_VERSION=24.20.0 ARG NODE_SHA256=2f2c0da162318f0de47665410c7c8c2ed3d36c8f3105de4bbc61176c70a7cbf2 +# Temurin rather than Debian's default-jdk, which is 17: the Java shim rewrites +# the port's call sites with java.lang.classfile, standard since 24. 25 is the +# long-term release above that floor. The tag carries a + that a URL cannot. +ARG JAVA_VERSION=25.0.4.1_1 +ARG JAVA_TAG=jdk-25.0.4.1%2B1 +ARG JAVA_SHA256=dbb698396d478e7fa2b1e50f4103324b2a99b90569ee27c33f2261f9215cf41e +# The SDK rather than the runtime: a .NET port arrives as source, and `dotnet +# run` compiles it. Checked against the sha512 Microsoft publishes beside the +# tarball, which is the checksum there is to check it against. +ARG DOTNET_VERSION=10.0.400 +ARG DOTNET_SHA512=1033977dd837150e0814cf0c5d5b17ceb63925fda7ba2158b47258a4bd7c048cf82eac3bc1166f3146f53124a3f5fba09db1de1260d2ce96399860303b404b48 ARG VINTBAS_RELEASE=vintbas-1.0.3-1 ARG VINTBAS_SHA256=72dda1d16ed21f0d812f6978a32d105dadea49dd8163692b44c462678eb16a17 @@ -58,6 +69,28 @@ RUN curl -fsSL -o /tmp/node.tar.xz "https://nodejs.org/dist/v${NODE_VERSION}/nod --exclude CHANGELOG.md --exclude LICENSE --exclude README.md \ && rm /tmp/node.tar.xz +RUN curl -fsSL -o /tmp/jdk.tar.gz \ + "https://github.com/adoptium/temurin25-binaries/releases/download/${JAVA_TAG}/OpenJDK25U-jdk_x64_linux_hotspot_${JAVA_VERSION}.tar.gz" \ + && echo "${JAVA_SHA256} /tmp/jdk.tar.gz" | sha256sum --check --strict - \ + && mkdir -p /usr/local/jdk \ + && tar --directory /usr/local/jdk --extract --file /tmp/jdk.tar.gz --strip-components 1 \ + && rm /tmp/jdk.tar.gz + +# libicu is what the .NET runtime uses for anything culture-aware, and without +# it the host refuses to start rather than quietly falling back -- which is the +# right way round, since a program that formats a number differently depending +# on which library it found is exactly the churn this image exists to remove. +RUN apt-get update \ + && apt-get install --no-install-recommends --yes libicu72 \ + && rm -rf /var/lib/apt/lists/* + +RUN curl -fsSL -o /tmp/dotnet.tar.gz \ + "https://builds.dotnet.microsoft.com/dotnet/Sdk/${DOTNET_VERSION}/dotnet-sdk-${DOTNET_VERSION}-linux-x64.tar.gz" \ + && echo "${DOTNET_SHA512} /tmp/dotnet.tar.gz" | sha512sum --check --strict - \ + && mkdir -p /usr/local/dotnet \ + && tar --directory /usr/local/dotnet --extract --file /tmp/dotnet.tar.gz \ + && rm /tmp/dotnet.tar.gz + # The reference BASIC interpreter, patched to seed its RNG from VINTBAS_SEED. # The same binary the Makefile installs, so a transcript recorded here and one # recorded on a developer's machine came from the same interpreter. @@ -66,7 +99,8 @@ RUN curl -fsSL -o /usr/local/bin/vintbas \ && echo "${VINTBAS_SHA256} /usr/local/bin/vintbas" | sha256sum --check --strict - \ && chmod +x /usr/local/bin/vintbas -ENV PATH=/usr/local/go/bin:/usr/local/bin:$PATH +ENV PATH=/usr/local/go/bin:/usr/local/jdk/bin:/usr/local/dotnet:/usr/local/bin:$PATH +ENV DOTNET_ROOT=/usr/local/dotnet # The rest of what moves. Each of these has been a transcript diff at some # point in somebody's life: @@ -78,6 +112,9 @@ ENV PATH=/usr/local/go/bin:/usr/local/bin:$PATH # PYTHONHASHSEED the iteration order of a set or a dict of strings # GOTOOLCHAIN stops the go command downloading a different Go than the one # pinned above, which would quietly unpin the image +# DOTNET_* the first `dotnet` command on a fresh machine prints a welcome +# banner and sends a telemetry ping, either of which would +# arrive in the middle of a transcript ENV LANG=C.UTF-8 \ LC_ALL=C.UTF-8 \ TZ=UTC \ @@ -85,7 +122,9 @@ ENV LANG=C.UTF-8 \ LINES=24 \ PYTHONHASHSEED=0 \ PYTHONDONTWRITEBYTECODE=1 \ - GOTOOLCHAIN=local + GOTOOLCHAIN=local \ + DOTNET_NOLOGO=1 \ + DOTNET_CLI_TELEMETRY_OPTOUT=1 # What a bug report has to carry, written from the binaries that were actually # installed rather than from the arguments above, so it cannot claim a version @@ -97,6 +136,8 @@ RUN { \ echo "arch=$(uname -m)"; \ echo "go=$(go version | cut -d' ' -f3)"; \ echo "node=$(node --version)"; \ + echo "java=$(java --version | head -n 1 | cut -d' ' -f2)"; \ + echo "dotnet=$(dotnet --version)"; \ echo "python=$(python3 --version | cut -d' ' -f2)"; \ echo "ruby=$(ruby --version | cut -d' ' -f2)"; \ echo "vintbas=${VINTBAS_RELEASE}"; \ diff --git a/docker/run.sh b/docker/run.sh index d7cef6d..8550726 100755 --- a/docker/run.sh +++ b/docker/run.sh @@ -13,6 +13,17 @@ # tmp/ is not: `make build_dev` in here produces a linux binary, and dropping # that on top of the one the host just built turns the next `make examples` # into "cannot execute binary file". +# +# The cache volumes are only about speed. Go, and .NET more so, rebuild the +# world in a fresh container, and `dotnet run` on a file-based app compiles the +# program every time it starts -- which happens once per scripted run rather +# than once per suite. Nothing in them affects what a program prints. +# +# Not ~/.dotnet, which looks like the obvious one and breaks the SDK: it holds +# the first-run sentinel, and the first run is also what creates ~/.local/share. +# Persist the sentinel without persisting the directory it stood for and every +# later run skips the setup, finds no local application data folder, and dies +# with "Unable to determine a temporary directory path". set -euo pipefail IMAGE="${PRESCRIPT_IMAGE_NAME:-prescript-env:dev}" @@ -62,6 +73,8 @@ exec docker run --rm ${INTERACTIVE[@]+"${INTERACTIVE[@]}"} ${SECCOMP[@]+"${SECCO --mount type=volume,source=prescript-tmp,target=/workspace/tmp \ --mount type=volume,source=prescript-go-build,target=/root/.cache/go-build \ --mount type=volume,source=prescript-go-mod,target=/root/go/pkg/mod \ + --mount type=volume,source=prescript-nuget,target=/root/.nuget/packages \ + --mount type=volume,source=prescript-dotnet,target=/root/.local/share/dotnet \ --env PRESCRIPT_IMAGE="$DIGEST" \ --env PRESCRIPT_REQUIRE_RUNNERS=1 \ "$IMAGE" "$@" diff --git a/docs/container.md b/docs/container.md index 479567a..d60b112 100644 --- a/docs/container.md +++ b/docs/container.md @@ -20,7 +20,8 @@ make docker_shell # look around | --- | --- | | Base | `debian:bookworm-slim` by digest | | Ruby, Python | Debian stable, a fixed series taking security fixes only | -| Go, Node | upstream tarballs, checked against a published SHA-256 | +| Go, Node, Java | upstream tarballs, checked against a published SHA-256 | +| .NET | the SDK tarball, checked against the SHA-512 Microsoft publishes | | vintbas | the same release asset the Makefile installs, checked the same way | | Locale | `LANG=LC_ALL=C.UTF-8` | | Timezone | `TZ=UTC` | @@ -72,6 +73,8 @@ base=debian:bookworm-slim@sha256:8820... arch=x86_64 go=go1.24.13 node=v24.20.0 +java=25.0.4.1 +dotnet=10.0.400 python=3.11.2 ruby=3.1.2p20 vintbas=vintbas-1.0.3-1 diff --git a/docs/determinism.md b/docs/determinism.md index b4bf4b5..c6ff7a3 100644 --- a/docs/determinism.md +++ b/docs/determinism.md @@ -58,8 +58,32 @@ prescript play scripts/33-dice.yaml --runner runners/ruby.yaml -- 33_Dice/ruby/d | Ruby | `RUBYOPT=-r` | `rand`, `Kernel#rand` | yes | | Python | `sitecustomize.py` on `PYTHONPATH` | the `random` module's functions | yes | | Node | `NODE_OPTIONS=--require ` | `Math.random` | yes | +| Java | `-javaagent:` rewriting call sites | `Math.random`, `Random`, `ThreadLocalRandom` | yes | +| .NET | a `System.Random` compiled in ahead of the real one | everything on `Random`, including `Shared` | yes | | Go | `GODEBUG=randautoseed=0` | `math/rand`'s global functions | no | +Java and .NET are the two that reach the program by getting in front of the +compiler rather than by setting a variable the runtime reads, because neither +runtime has a variable that would do. + +The Java agent rewrites the port's own bytecode as each class loads: a call to +`Random.nextInt()` becomes a call to the shim, which returns the next tape value +and ignores the generator it was called on. It rewrites the port and leaves the +JDK alone, so no platform class is patched and no retransformation happens. The +agent is a jar, and the only shim that has to be built before it can be used: + +``` +make shims +``` + +The .NET shim is a source file declaring `namespace System { public class Random }`. +The C# compiler prefers a type it is compiling over the same type from a +reference, so the port's `new Random()` binds to the shim without the port +changing a line. `runners/dotnet.yaml` adds that file to the compilation with an +MSBuild targets file, which works the same for a single `.cs` file as for a +`.csproj`. It is the widest of the shims by accident of the mechanism: replacing +the class replaces `Shuffle`, `GetItems` and `Random.Shared` along with the draws. + Go seeds but cannot be taped. `GODEBUG` turns off the automatic seeding that Go 1.20 introduced, which is enough to make one build repeatable, but there is no exported way to put a different source behind `math/rand`'s package-level @@ -80,32 +104,39 @@ program constructs for itself, or one that seeds itself deliberately: - Ruby: `Random.new(...)`, `SecureRandom` - Python: `random.Random(...)` instances, `secrets`, `numpy` - Node: `crypto.randomBytes`, `crypto.getRandomValues` +- Java: `SecureRandom`, `SplittableRandom`, generators built by + `RandomGeneratorFactory`, and draws made from inside `java.base` rather than + from the port — `Collections.shuffle(list, rnd)` and `rnd.ints()` call + `nextInt` at a call site the agent does not rewrite +- .NET: `System.Security.Cryptography`, `Guid.NewGuid`, and any draw made + inside a pre-compiled dependency, which was compiled against the real + `Random` before the shim existed - Go: `math/rand/v2`, which has no global seed and ignores `GODEBUG` — verified, not assumed A port using one of those needs either its own runner or a [redaction](script-format.md#redactions) for the values it prints. -Node is the one replacement rather than a seeding: V8's `Math.random` cannot be -seeded — there is no API, and the engine takes entropy when a context is -created — so the shim substitutes mulberry32, small enough to read in one -sitting and identical on every platform. +Node and .NET are replacements rather than seedings. V8's `Math.random` cannot +be seeded — there is no API, and the engine takes entropy when a context is +created — and the .NET shim has replaced `Random` outright by the time the port +asks for one, so there is nothing left underneath to seed. Both substitute +mulberry32, small enough to read in one sitting and identical on every +platform. ### Not yet shipped | Language | Mechanism | Why it is not here | | --- | --- | --- | -| .NET | `DOTNET_STARTUP_HOOKS` | no toolchain to verify it against | -| Java | `-javaagent` instrumenting `Math.random` / `Random` | no toolchain to verify it against | | Rust | `[patch.crates-io] getrandom` in `.cargo/config.toml` | build-time, not launch-time | | Haskell | vendored `random` with `initStdGen = pure (mkStdGen n)` | build-time, not launch-time | | C / C++ | `-include shim.h`, or a `rand.o` linked ahead of libc | build-time, not launch-time | -The first two are runners waiting for a machine to test them on. The last three -are a different problem: a compiled language's randomness is decided when it is -built, and a runner only gets to speak at launch. Those need the build to -cooperate, which is what makes the [pinned image](container.md) the place they -belong. +These are all the same problem: a compiled language's randomness is decided when +it is built, and a runner only gets to speak at launch. Java and .NET are in the +table above rather than in this one because both compile on the way to running, +which gives a runner a compilation to join; a Rust port arrives as a binary, or +as a build a runner would have to drive. An untested runner is worse than a missing one — it makes a corpus look seeded when it is not — so these are listed rather than guessed at. @@ -122,18 +153,24 @@ It looks like the general answer and is not: ## What a seed does not buy -The same seed does not mean the same numbers. Ruby, Python, Node and Go each -draw a different sequence from `PRESCRIPT_SEED=0`, because each has a different -generator underneath. The test fixtures show it plainly — one program, one -seed, four answers: +The same seed does not mean the same numbers. Each language draws a different +sequence from `PRESCRIPT_SEED=0`, because each has a different generator +underneath. The test fixtures show it plainly — one program, one seed: | Language | First three draws | | --- | --- | | Ruby | `548 715 602` | | Python | `844 757 420` | | Node | `358 105 675` | +| Java | `730 240 637` | +| .NET | `358 105 675` | | Go | `604 940 664` | +.NET agrees with Node because both shims substitute the same generator, for the +reason given above. Java's row is the JDK's own LCG, seeded the ordinary way. +That one agreement is a fact about two shims rather than a property anything +should lean on — a tape is how ports are made to agree on purpose. + So a seed makes each port repeatable, and one expected-output file still cannot serve them all. That is what a tape is for. @@ -152,8 +189,8 @@ prescript play scripts/33-dice.yaml --runner runners/ruby.yaml \ loaded switches from seeding to replaying. Nothing else about the run changes, and the port is still untouched. -The same tape through the Ruby, Python and Node runners gives the same -transcript — which is the whole point, and is what +The same tape through the Ruby, Python, Node, Java and .NET runners gives the +same transcript — which is the whole point, and is what `TestOneTapeGivesEveryLanguageTheSameNumbers` checks. ### Where the numbers come from diff --git a/internal/play/runner_integration_test.go b/internal/play/runner_integration_test.go index a326a33..47d502c 100644 --- a/internal/play/runner_integration_test.go +++ b/internal/play/runner_integration_test.go @@ -21,8 +21,15 @@ import ( // // They are the language's documented sequence for that seed, not a snapshot of // one machine's: Ruby and Python both promise a reproducible Mersenne Twister, -// Go's is the fixed source it used before it started seeding itself, and +// Go's is the fixed source it used before it started seeding itself, Java's is +// the linear congruential generator java.util.Random specifies exactly, and // Node's is the generator in runners/node/random.js. +// +// .NET draws what Node draws, and that is not a mistake. Its shim replaces +// System.Random outright, so it has to bring a generator rather than seed one, +// and it brings the same mulberry32 the Node shim already carries instead of a +// second one to explain. Two languages agreeing under a seed is a coincidence +// of the shims; a tape is what makes agreement mean something. var seededRunners = []struct { runner string program string @@ -32,6 +39,8 @@ var seededRunners = []struct { {runner: "python.yaml", program: "rng.py", drawn: "844 757 420"}, {runner: "node.yaml", program: "rng.js", drawn: "358 105 675"}, {runner: "go.yaml", program: "rng.go", drawn: "604 940 664"}, + {runner: "java.yaml", program: "rng.java", drawn: "730 240 637"}, + {runner: "dotnet.yaml", program: "rng.cs", drawn: "358 105 675"}, } func repositoryPath(t *testing.T, parts ...string) string { @@ -55,7 +64,8 @@ func repositoryPath(t *testing.T, parts ...string) string { // turn the build red rather than quietly shrink what is being checked. func loadRunner(t *testing.T, name string) script.Runner { t.Helper() - runner, err := script.ParseRunnerFromFile(repositoryPath(t, "runners", name)) + directory := repositoryPath(t, "runners") + runner, err := script.ParseRunnerFromFile(filepath.Join(directory, name)) assert.NoError(t, err) if _, err := exec.LookPath(runner.Executable); err != nil { @@ -65,9 +75,65 @@ func loadRunner(t *testing.T, name string) script.Runner { t.Skipf("%s is not installed, so %s cannot be checked here", runner.Executable, name) } + if shim := missingShim(runner, directory); shim != "" { + if os.Getenv("PRESCRIPT_REQUIRE_RUNNERS") != "" { + t.Fatalf("%s does not exist, so %s cannot be checked, and PRESCRIPT_REQUIRE_RUNNERS says it has to be; run make shims", shim, name) + } + t.Skipf("%s does not exist, so %s cannot be checked here; run make shims", shim, name) + } + return runner } +// missingShim names a file the runner points at that is not there. +// +// The Java shim is built rather than checked in, and a runner whose jar is +// missing fails the same way a broken shim would: the program runs, draws its +// own numbers and disagrees with the script. That is a confusing way to be +// told to run make shims. +// +// Written as a search for the runner's own directory rather than a check of +// whole values, because a shim is always named inside something else -- +// -javaagent:, -r, --property:Name=. +func missingShim(runner script.Runner, directory string) string { + values := append([]string{}, runner.Arguments...) + for _, value := range runner.Env { + values = append(values, value) + } + + for _, value := range values { + start := strings.Index(value, directory) + if start < 0 { + continue + } + + path := strings.FieldsFunc(value[start:], func(r rune) bool { return r == ' ' || r == '"' })[0] + if _, err := os.Stat(path); err != nil { + return path + } + } + + return "" +} + +// withoutShims keeps the arguments that are only how a language is started -- +// `go run`, `dotnet run` -- and drops the ones that activate a shim. +// +// Both kinds live in the same list, so dropping the list wholesale would be +// testing that `go` with no subcommand fails, which it does for reasons that +// have nothing to do with randomness. The rule is the same one missingShim +// uses: an argument that names something in the runner's own directory is the +// runner doing its job, and everything else is just the command line. +func withoutShims(runner script.Runner, directory string) []string { + var kept []string + for _, argument := range runner.Arguments { + if !strings.Contains(argument, directory) { + kept = append(kept, argument) + } + } + return kept +} + // drawingRun scripts one of the rng fixtures: it is asked for as many numbers // as `drawn` names, and has to print exactly those. func drawingRun(t *testing.T, program string, drawn string) script.Run { @@ -119,7 +185,17 @@ func TestWithoutARunnerTheSameProgramIsUnscriptable(t *testing.T) { run := drawingRun(t, language.program, language.drawn) run.Executable = runner.Executable - run.RunnerArguments = runner.Arguments + run.RunnerArguments = withoutShims(runner, repositoryPath(t, "runners")) + + // TERM comes along for the same reason `dotnet run` does: it is + // how the language is started rather than how it is seeded. Left + // out, .NET's console announces itself in escape codes ahead of + // the program's first prompt, and this test fails a step earlier + // than it means to, for a reason that is not randomness. + if term, set := runner.Env["TERM"]; set { + run.InheritEnv = true + run.Env = map[string]string{"TERM": term} + } exitCode := 0 report := captureStderr(t, func() { @@ -144,6 +220,8 @@ var tapedRunners = []struct { {runner: "ruby.yaml", program: "rng.rb"}, {runner: "python.yaml", program: "rng.py"}, {runner: "node.yaml", program: "rng.js"}, + {runner: "java.yaml", program: "rng.java"}, + {runner: "dotnet.yaml", program: "rng.cs"}, } // referenceDraws is what the reference BASIC interpreter itself prints for diff --git a/runners/dotnet.yaml b/runners/dotnet.yaml new file mode 100644 index 0000000..f845ce6 --- /dev/null +++ b/runners/dotnet.yaml @@ -0,0 +1,49 @@ +# How to start a .NET port, and how to make its randomness repeatable. +# +# prescript play dice.yaml --runner runners/dotnet.yaml +# +# `dotnet run` takes either shape a port comes in: a file-based app, which the +# .NET 10 SDK compiles and runs in one step the way `go run` does, or a project +# given as `--project `. +version: "0.8" +executable: dotnet + +# Alone among these runners, this one is activated by the compiler rather than +# at launch: the shim declares System.Random in source, and the C# compiler +# prefers a type it can see the source of. This property is how the shim gets +# into a build the port did not ask for it in. ${runnerDir} is where this file +# lives, so the runner and its shim travel together whatever directory +# prescript is run from. +# +# On the command line rather than in env, though MSBuild reads a variable of +# the same name: a file-based app is built through the SDK in-process, where +# the environment does not become MSBuild properties. A property reaches both +# shapes. See runners/dotnet/prescript.targets. +arguments: ["run", "--property:CustomBeforeMicrosoftCommonTargets=${runnerDir}/dotnet/prescript.targets"] + +env: + # One variable seeds every language. Two ports of the same program still draw + # different numbers from it -- that is what a tape fixes, not a seed -- but + # each of them draws the same numbers every time. + PRESCRIPT_SEED: "0" + + # The first `dotnet` command on a fresh machine prints a welcome banner and + # sends a telemetry ping. The banner would arrive in the middle of the + # transcript being compared, on exactly the runs least likely to be looked at + # twice. + DOTNET_NOLOGO: "1" + DOTNET_CLI_TELEMETRY_OPTOUT: "1" + + # System.Console sends the terminal's keypad-application string the first + # time a .NET program reads a key, and on a pty that lands in the transcript + # ahead of the program's first prompt. There is no switch for it, so the + # answer is to say the terminal has no such trick to play. Console.Clear and + # the colour properties still work under it; they simply stop emitting + # escape sequences that the reference interpreter was never going to emit + # either. + TERM: "dumb" + +# The SDK finds its runtimes, its NuGet cache and its home directory through +# the environment. Pinning the environment is a container's job rather than a +# runner's. +inheritEnv: true diff --git a/runners/dotnet/prescript.targets b/runners/dotnet/prescript.targets new file mode 100644 index 0000000..3711ea6 --- /dev/null +++ b/runners/dotnet/prescript.targets @@ -0,0 +1,23 @@ + + + + $(NoWarn);436 + + + + + + diff --git a/runners/dotnet/prescript/Random.cs b/runners/dotnet/prescript/Random.cs new file mode 100644 index 0000000..643148a --- /dev/null +++ b/runners/dotnet/prescript/Random.cs @@ -0,0 +1,306 @@ +// Makes a .NET port's randomness repeatable, in one of two ways. +// +// With PRESCRIPT_TAPE set, every draw returns a value recorded from the +// reference BASIC interpreter, in order, so this port and every other port of +// the same program draw the same numbers. Without it the draws come from a +// seeded generator of this file's own, which makes this port repeatable but +// leaves it drawing a different sequence from most other languages. See +// docs/determinism.md. +// +// Activated by compiling this file into the port, which prescript.targets does +// without the port being edited. Declaring System.Random in source shadows the +// runtime's: the C# compiler prefers a type it can see the source of, so every +// `new Random()`, `Random.Shared` and `rnd.Next()` in the port binds here +// instead of to System.Private.CoreLib. +// +// The other shims replace a function at run time. .NET has no seam for that: +// `new Random()` takes entropy in a constructor with no global seed to set, +// and reaching its methods afterwards means detouring compiled code, which +// needs a bytecode library that has to be taught about every new runtime. The +// compiler is the seam .NET does have, and it needs nothing but source. +// +// What this does not reach: RandomNumberGenerator and the rest of +// System.Security.Cryptography, Guid.NewGuid, and anything a NuGet dependency +// compiled for itself before it got here. + +// Nullable annotations are a property of the port, not of this file, and this +// file is compiled into ports that have made either choice. Turning them off +// here keeps it from warning in one kind of project or the other. +#nullable disable + +namespace System +{ + /// + /// System.Random's surface, answered from one place. + /// + /// Everything is virtual where the real one is virtual, so a port that + /// subclasses Random still compiles and still overrides what it meant to. + /// The seed a constructor is handed is ignored on purpose: a port that + /// seeds itself is repeatable already, and what is wanted here is for it + /// to be repeatable in step with every other port of the same program. + /// + public class Random + { + public static Random Shared { get; } = new Random(); + + public Random() + { + } + + // Named as the runtime names it, capital and all, so a port calling + // new Random(Seed: 42) still compiles. + public Random(int Seed) + { + } + + public virtual int Next() => (int)(global::Prescript.Tape.Next() * int.MaxValue); + + // What a BASIC port writes for INT(RND(1) * N), and what the other + // shims do with the same value, so one tape means one number. + public virtual int Next(int maxValue) => (int)(global::Prescript.Tape.Next() * maxValue); + + public virtual int Next(int minValue, int maxValue) => + minValue + (int)(global::Prescript.Tape.Next() * ((long)maxValue - minValue)); + + public virtual double NextDouble() => global::Prescript.Tape.Next(); + + public virtual float NextSingle() => (float)global::Prescript.Tape.Next(); + + public virtual long NextInt64() => (long)(global::Prescript.Tape.Next() * long.MaxValue); + + public virtual long NextInt64(long maxValue) => (long)(global::Prescript.Tape.Next() * maxValue); + + public virtual long NextInt64(long minValue, long maxValue) => + minValue + (long)(global::Prescript.Tape.Next() * ((double)maxValue - minValue)); + + public virtual void NextBytes(byte[] buffer) => NextBytes(new Span(buffer)); + + // One draw per byte, which is what makes a count of draws comparable + // between a port that asks for bytes and one that asks for numbers. + public virtual void NextBytes(Span buffer) + { + for (int index = 0; index < buffer.Length; index++) + { + buffer[index] = (byte)(global::Prescript.Tape.Next() * 256); + } + } + + protected virtual double Sample() => global::Prescript.Tape.Next(); + + public T[] GetItems(T[] choices, int length) => GetItems(new ReadOnlySpan(choices), length); + + public T[] GetItems(ReadOnlySpan choices, int length) + { + T[] chosen = new T[length]; + GetItems(choices, new Span(chosen)); + return chosen; + } + + public void GetItems(ReadOnlySpan choices, Span destination) + { + for (int index = 0; index < destination.Length; index++) + { + destination[index] = choices[Next(choices.Length)]; + } + } + + public void Shuffle(T[] values) => Shuffle(new Span(values)); + + // The same Fisher-Yates the runtime's own Shuffle does, drawing the + // same number of times, so a port that shuffles stays in step with one + // that picks indexes by hand. + public void Shuffle(Span values) + { + for (int index = 0; index < values.Length - 1; index++) + { + int swap = Next(index, values.Length); + (values[index], values[swap]) = (values[swap], values[index]); + } + } + } +} + +namespace Prescript +{ + using System; + using System.IO; + + /// + /// Where the numbers come from. + /// + /// A port built from several projects compiles this file once per + /// assembly, and separate copies drawing separately would put the same + /// program out of step with itself. The drawing function is therefore + /// created once and parked on the AppDomain, where every copy finds it: + /// the copies are different types, but Func<double> is the runtime's + /// own, so they can all hold the same one. + /// + internal static class Tape + { + private const string Key = "prescript.random.draw"; + + private static readonly Func Draw = Install(); + + public static double Next() => Draw(); + + private static Func Install() + { + // The AppDomain is the one object every copy of this file + // already agrees on, which is exactly what makes it the thing to + // lock while deciding who creates the shared function. + lock (AppDomain.CurrentDomain) + { + if (AppDomain.CurrentDomain.GetData(Key) is Func shared) + { + return shared; + } + + Func draw = Create(); + AppDomain.CurrentDomain.SetData(Key, draw); + return draw; + } + } + + private static Func Create() + { + string path = Environment.GetEnvironmentVariable("PRESCRIPT_TAPE"); + if (string.IsNullOrEmpty(path)) + { + return Seeded(Environment.GetEnvironmentVariable("PRESCRIPT_SEED")); + } + + double[] values = Read(path); + Action record = Usage(Environment.GetEnvironmentVariable("PRESCRIPT_TAPE_USAGE")); + int drawn = 0; + + return () => + { + // Running off the end is an error rather than a wrap. A port + // that draws more than the reference did has restructured how + // it consumes randomness, which is a finding; silently + // starting the tape again would turn that finding into a + // transcript that merely looks wrong somewhere further on. + // + // Reported and exited rather than thrown, because a thrown + // error arrives as a stack trace and the line that says what + // went wrong scrolls off the top of the failure report. + if (drawn >= values.Length) + { + Console.Error.WriteLine("prescript: the tape ran out after " + values.Length + + " values; this port draws more randomness than the reference did"); + Environment.Exit(1); + } + + double value = values[drawn++]; + record(drawn); + return value; + }; + } + + private static double[] Read(string path) + { + try + { + var values = new System.Collections.Generic.List(); + foreach (string line in File.ReadLines(path)) + { + string trimmed = line.Trim(); + if (trimmed.Length == 0 || trimmed[0] == '#') + { + continue; + } + + values.Add(double.Parse(trimmed, global::System.Globalization.CultureInfo.InvariantCulture)); + } + + return values.ToArray(); + } + catch (Exception failure) + { + Console.Error.WriteLine("prescript: could not read the tape " + path + ": " + failure.Message); + Environment.Exit(1); + return null; + } + } + + /// + /// How much of the tape a port used is the number that separates a + /// real logic bug from a port that restructured its draws, so it is + /// written down rather than left to be inferred from the transcript. + /// + /// Rewritten after every draw rather than once on exit, because the + /// number that matters is how much had been drawn when the run stopped + /// agreeing with the transcript -- and a run that diverged by hanging + /// is killed, which runs no exit handler at all. Rewriting at offset 0 + /// is safe without truncating: the count only ever grows, so its + /// decimal form only ever gets longer and each write covers the last. + /// + private static Action Usage(string path) + { + if (string.IsNullOrEmpty(path)) + { + return drawn => { }; + } + + FileStream file; + try + { + file = new FileStream(path, FileMode.Create, FileAccess.Write, FileShare.ReadWrite); + } + catch (Exception) + { + // A report that cannot say how much was drawn is worth less + // than one that can, and worth far more than a run killed for + // failing to say it. + return drawn => { }; + } + + Action record = drawn => + { + try + { + byte[] count = global::System.Text.Encoding.UTF8.GetBytes(drawn + "\n"); + file.Seek(0, SeekOrigin.Begin); + file.Write(count, 0, count.Length); + file.Flush(true); + } + catch (Exception) + { + } + }; + + // Written from the start, so that a port which drew nothing at all + // says so rather than saying nothing. + record(0); + return record; + } + + /// + /// mulberry32, the same generator the Node shim uses, and for the same + /// reason: short enough to read in one sitting, and its whole state is + /// a single 32-bit word, which is what makes the sequence identical + /// everywhere. Two shims sharing an algorithm is not a coincidence to + /// hide -- seeded .NET and seeded Node draw the same numbers, which is + /// as much as a seed can offer and less than a tape does. + /// + /// The runtime's own seeded Random is unreachable from here: this file + /// is what System.Random means in the compilation it is part of. + /// + private static Func Seeded(string seed) + { + uint state = unchecked((uint)(int.TryParse(seed, out int parsed) ? parsed : 0) + 0x9e3779b9u); + + return () => + { + unchecked + { + state += 0x6d2b79f5u; + uint t = state; + t = (t ^ (t >> 15)) * (t | 1u); + t ^= t + (t ^ (t >> 7)) * (t | 61u); + return ((t ^ (t >> 14)) & uint.MaxValue) / 4294967296.0; + } + }; + } + } +} diff --git a/runners/java.yaml b/runners/java.yaml new file mode 100644 index 0000000..9c8645c --- /dev/null +++ b/runners/java.yaml @@ -0,0 +1,34 @@ +# How to start a Java port, and how to make its randomness repeatable. +# +# prescript play dice.yaml --runner runners/java.yaml +# +# The port is a source file: `java Rng.java` compiles and runs it in one step, +# the way `go run` does, so a corpus can hold sources rather than builds. +version: "0.8" +executable: java + +# The JVM loads this before the program's main method, so a port does not have +# to know it exists and does not have to be edited. ${runnerDir} is where this +# file lives, so the runner and its shim travel together whatever directory +# prescript is run from. +# +# An argument rather than an environment variable: JDK_JAVA_OPTIONS would work, +# and the launcher announces on stderr that it picked it up, which lands in the +# middle of the transcript being compared. +# +# The jar is built rather than checked in -- `make shims`, which the container +# and CI both run. It needs a JDK 24 or newer, because the shim rewrites the +# port's calls with java.lang.classfile rather than a third-party bytecode +# library. See runners/java/prescript/Agent.java. +arguments: ["-javaagent:${runnerDir}/java/prescript-agent.jar"] + +env: + # One variable seeds every language. Two ports of the same program still draw + # different numbers from it -- that is what a tape fixes, not a seed -- but + # each of them draws the same numbers every time. + PRESCRIPT_SEED: "0" + +# A JDK installed by sdkman, jenv or asdf is found through the environment, and +# a port with dependencies resolves them through it too. Pinning the +# environment is a container's job rather than a runner's. +inheritEnv: true diff --git a/runners/java/manifest.txt b/runners/java/manifest.txt new file mode 100644 index 0000000..ca0e222 --- /dev/null +++ b/runners/java/manifest.txt @@ -0,0 +1,2 @@ +Premain-Class: prescript.Agent +Can-Retransform-Classes: false diff --git a/runners/java/prescript/Agent.java b/runners/java/prescript/Agent.java new file mode 100644 index 0000000..0a0a10d --- /dev/null +++ b/runners/java/prescript/Agent.java @@ -0,0 +1,176 @@ +package prescript; + +import java.lang.classfile.ClassFile; +import java.lang.classfile.ClassTransform; +import java.lang.classfile.CodeTransform; +import java.lang.classfile.instruction.InvokeInstruction; +import java.lang.constant.ClassDesc; +import java.lang.constant.MethodTypeDesc; +import java.lang.instrument.ClassFileTransformer; +import java.lang.instrument.Instrumentation; +import java.security.ProtectionDomain; +import java.util.HashMap; +import java.util.Map; +import java.util.concurrent.atomic.AtomicBoolean; + +/** + * Makes a Java port's randomness repeatable without editing the port. + * + *

Activated by -javaagent:<this jar>, which the JVM loads before the + * program's main method, so the program does not have to know it exists. + * + *

Unlike the Ruby, Python and Node shims, this one cannot simply replace a + * function: Java resolves java.util.Random's methods at the call site and + * there is no global to reassign. So it rewrites the call sites instead. Every + * class the program loads is read on its way in, and each call to Math.random + * or to one of Random's drawing methods is re-pointed at {@link Tape}, which + * answers from the tape or from one seeded generator. + * + *

Rewriting the program rather than the JDK is the deliberate choice. + * Redefining java.util.Random itself would reach further -- Collections.shuffle + * and the random streams draw through it -- but it means retransforming a core + * class that is loaded and compiled before any agent runs. The program's own + * classes are loaded after this transformer is installed, so they are rewritten + * on the way in, which needs no retransformation and cannot leave the JDK in a + * state it was not built for. + * + *

The rewrite is done with java.lang.classfile, the class-file API the JDK + * has shipped since 24. That is why this runner asks for a JDK that new: the + * alternative is a third-party bytecode library, and a pinned environment is + * worth more than support for an older JVM that nothing here has to run on. + * + *

What this does not reach: SecureRandom, SplittableRandom, a generator + * built by RandomGeneratorFactory, and any draw made inside the JDK on the + * program's behalf -- Collections.shuffle(list, rnd), rnd.ints(), and the rest + * of the stream methods. + */ +public final class Agent { + private static final ClassDesc TAPE = ClassDesc.of("prescript.Tape"); + + /** + * The receiver becomes the first argument and is then ignored. It has to + * be taken because the call site leaves it on the stack, and ignoring it + * is what makes every generator in a program draw from one place. + */ + private static final String GENERATOR = "Ljava/util/random/RandomGenerator;"; + + /** + * Owners whose drawing methods are redirected. Random covers a port that + * holds a Random, RandomGenerator one that holds the interface, and + * ThreadLocalRandom the modern way of asking for the same thing. + * + *

SecureRandom is not here on purpose. It extends Random, so it would + * cost one line -- but a program that asks for cryptographic randomness + * has asked for something a recorded tape is not, and quietly answering it + * from a text file is not a decision to take on a program's behalf. + */ + private static final String[] OWNERS = { + "java/util/Random", + "java/util/random/RandomGenerator", + "java/util/concurrent/ThreadLocalRandom", + }; + + /** Drawing methods, by descriptor, and what each becomes. */ + private static final String[][] DRAWS = { + {"nextDouble", "()D"}, + {"nextFloat", "()F"}, + {"nextBoolean", "()Z"}, + {"nextInt", "()I"}, + {"nextInt", "(I)I"}, + {"nextInt", "(II)I"}, + {"nextLong", "()J"}, + }; + + private static final Map REDIRECTS = redirects(); + + private Agent() { + } + + public static void premain(String arguments, Instrumentation instrumentation) { + instrumentation.addTransformer(new Redirector()); + } + + private record Redirect(String name, MethodTypeDesc descriptor) { + } + + private static Map redirects() { + Map redirects = new HashMap<>(); + redirects.put("java/lang/Math.random()D", + new Redirect("random", MethodTypeDesc.ofDescriptor("()D"))); + + for (String owner : OWNERS) { + for (String[] draw : DRAWS) { + String name = draw[0]; + String descriptor = draw[1]; + redirects.put(owner + "." + name + descriptor, + new Redirect(name, MethodTypeDesc.ofDescriptor("(" + GENERATOR + descriptor.substring(1)))); + } + } + return redirects; + } + + private static final class Redirector implements ClassFileTransformer { + /** + * Whether this class belongs to the runtime rather than to the program + * under test. + * + *

The bootstrap loader is the obvious half. The other half is less + * obvious and matters more: java rng.java compiles the source in this + * same JVM, so javac's own classes -- loaded by the platform loader, + * which is not null -- come past here too, and rewriting a compiler's + * draws would spend the tape before the program had started. + */ + private static boolean platform(Module module, ClassLoader loader) { + if (loader == null) { + return true; + } + if (module == null || !module.isNamed()) { + return false; + } + + String moduleName = module.getName(); + return moduleName.equals("java") || moduleName.startsWith("java.") + || moduleName.equals("jdk") || moduleName.startsWith("jdk."); + } + + @Override + public byte[] transform(Module module, ClassLoader loader, String name, + Class beingRedefined, ProtectionDomain domain, byte[] original) { + if (name == null || name.startsWith("prescript/") || platform(module, loader)) { + return null; + } + + try { + AtomicBoolean rewrote = new AtomicBoolean(); + CodeTransform redirect = (builder, element) -> { + if (element instanceof InvokeInstruction invoke) { + Redirect target = REDIRECTS.get(invoke.owner().asInternalName() + + "." + invoke.name().stringValue() + invoke.type().stringValue()); + if (target != null) { + builder.invokestatic(TAPE, target.name(), target.descriptor()); + rewrote.set(true); + return; + } + } + builder.with(element); + }; + + ClassFile classFile = ClassFile.of(); + byte[] rewritten = classFile.transformClass(classFile.parse(original), + ClassTransform.transformingMethodBodies(redirect)); + + // Null means "left alone", which is both faster and safer than + // handing back a re-encoded copy of a class nothing was going + // to change. + return rewrote.get() ? rewritten : null; + } catch (Throwable failure) { + // Said out loud rather than swallowed. A transformer that + // throws is ignored by the JVM, and a port that quietly went + // back to drawing its own numbers is exactly the silent + // failure this whole exercise exists to prevent. + System.err.println("prescript: could not redirect randomness in " + name + ": " + failure); + return null; + } + } + } +} diff --git a/runners/java/prescript/Tape.java b/runners/java/prescript/Tape.java new file mode 100644 index 0000000..2c231c7 --- /dev/null +++ b/runners/java/prescript/Tape.java @@ -0,0 +1,183 @@ +package prescript; + +import java.io.BufferedReader; +import java.io.FileReader; +import java.io.RandomAccessFile; +import java.util.Random; +import java.util.random.RandomGenerator; + +/** + * Where a Java port's randomness comes from once the agent has redirected it, + * in one of two ways. + * + *

With PRESCRIPT_TAPE set, every draw returns a value recorded from the + * reference BASIC interpreter, in order, so this port and every other port of + * the same program draw the same numbers. Without it, one seeded + * {@link Random} answers every draw, which makes this port repeatable but + * leaves it drawing a different sequence from every other language. See + * docs/determinism.md. + * + *

Every method takes the generator the port called, and ignores it. That is + * the point: two Random instances in one program, and Math.random's own, all + * draw from here, so the order of the draws is the order the program makes + * them rather than an accident of how many generators it built. + * + *

Lives in the agent jar, which the JVM appends to the system class path + * when it loads the agent, so rewritten port code can reach it by name. + */ +public final class Tape { + private static final double[] VALUES = readTape(System.getenv("PRESCRIPT_TAPE")); + private static final Random SEEDED = VALUES == null ? seededGenerator() : null; + private static final RandomAccessFile USAGE = openUsage(System.getenv("PRESCRIPT_TAPE_USAGE")); + + private static int drawn; + + private Tape() { + } + + /** Math.random(). */ + public static double random() { + return next(); + } + + public static double nextDouble(RandomGenerator generator) { + return next(); + } + + public static float nextFloat(RandomGenerator generator) { + return (float) next(); + } + + public static boolean nextBoolean(RandomGenerator generator) { + return next() < 0.5; + } + + public static int nextInt(RandomGenerator generator, int bound) { + // What a BASIC port writes for INT(RND(1) * N), and what the other + // shims do with the same value, so one tape means one number. + return (int) (next() * bound); + } + + public static int nextInt(RandomGenerator generator, int origin, int bound) { + return origin + (int) (next() * (bound - origin)); + } + + public static int nextInt(RandomGenerator generator) { + // Spread over the whole range, which is what nextInt() promises. Ports + // of these games do not use it; it is here so that one that does is + // still repeatable rather than silently drawing from somewhere else. + return (int) (next() * 4294967296.0 + Integer.MIN_VALUE); + } + + public static long nextLong(RandomGenerator generator) { + return (long) ((next() - 0.5) * 2.0 * Long.MAX_VALUE); + } + + private static synchronized double next() { + if (VALUES == null) { + drawn++; + recordUsage(); + return SEEDED.nextDouble(); + } + + // Running off the end is an error rather than a wrap. A port that + // draws more than the reference did has restructured how it consumes + // randomness, which is a finding; silently starting the tape again + // would turn that finding into a transcript that merely looks wrong + // somewhere further on. + // + // Reported and exited rather than thrown, because a thrown error + // arrives as a stack trace and the line that says what went wrong + // scrolls off the top of the failure report. + if (drawn >= VALUES.length) { + System.err.println("prescript: the tape ran out after " + VALUES.length + + " values; this port draws more randomness than the reference did"); + System.exit(1); + } + + double value = VALUES[drawn++]; + recordUsage(); + return value; + } + + private static Random seededGenerator() { + String seed = System.getenv("PRESCRIPT_SEED"); + return new Random(seed == null || seed.isEmpty() ? 0L : Long.parseLong(seed.trim())); + } + + private static double[] readTape(String path) { + if (path == null || path.isEmpty()) { + return null; + } + + try (BufferedReader reader = new BufferedReader(new FileReader(path))) { + double[] values = new double[64]; + int count = 0; + for (String line = reader.readLine(); line != null; line = reader.readLine()) { + line = line.strip(); + if (line.isEmpty() || line.startsWith("#")) { + continue; + } + if (count == values.length) { + double[] grown = new double[count * 2]; + System.arraycopy(values, 0, grown, 0, count); + values = grown; + } + values[count++] = Double.parseDouble(line); + } + + double[] exact = new double[count]; + System.arraycopy(values, 0, exact, 0, count); + return exact; + } catch (Exception failure) { + System.err.println("prescript: could not read the tape " + path + ": " + failure); + System.exit(1); + return null; + } + } + + /** + * How much of the tape a port used is the number that separates a real + * logic bug from a port that restructured its draws, so it is written down + * rather than left to be inferred from the transcript. Written from the + * start, so that a port which drew nothing at all says so rather than + * saying nothing. + */ + private static RandomAccessFile openUsage(String path) { + if (path == null || path.isEmpty()) { + return null; + } + + try { + RandomAccessFile file = new RandomAccessFile(path, "rws"); + file.setLength(0); + file.write("0\n".getBytes()); + return file; + } catch (Exception failure) { + return null; + } + } + + /** + * Rewritten after every draw rather than once on exit, because the number + * that matters is how much had been drawn when the run stopped agreeing + * with the transcript -- and a run that diverged by hanging is killed, + * which runs no shutdown hook at all. Rewriting at offset 0 is safe + * without truncating: the count only ever grows, so its decimal form only + * ever gets longer and each write covers the last. + */ + private static void recordUsage() { + if (USAGE == null) { + return; + } + + try { + USAGE.seek(0); + USAGE.write((drawn + "\n").getBytes()); + } catch (Exception ignored) { + // A report that cannot say how much was drawn is worth less than + // one that can, and worth far more than a run killed for failing + // to say it. + } + } +} diff --git a/test/fixtures/rng/rng.cs b/test/fixtures/rng/rng.cs new file mode 100644 index 0000000..47767fc --- /dev/null +++ b/test/fixtures/rng/rng.cs @@ -0,0 +1,20 @@ +// A port in miniature: it asks something, then prints numbers it drew at +// random. Without a seed those numbers differ on every run, which is what makes +// a program like this impossible to script. +// +// Run by dotnet run rng.cs, the file-based app the .NET 10 SDK compiles and +// runs in one step, which is the analogue of go run and java Rng.java. + +Console.Write("HOW MANY? "); +int count = int.Parse(Console.ReadLine()!.Trim()); + +var random = new Random(); +var drawn = new string[count]; +for (int index = 0; index < count; index++) +{ + // INT(RND(1) * 1000), the way a port translates it. Written the same way + // in every language here, so a tape gives all of them the same numbers. + drawn[index] = ((int)(random.NextDouble() * 1000)).ToString(); +} + +Console.WriteLine(string.Join(" ", drawn)); diff --git a/test/fixtures/rng/rng.java b/test/fixtures/rng/rng.java new file mode 100644 index 0000000..f64bf77 --- /dev/null +++ b/test/fixtures/rng/rng.java @@ -0,0 +1,34 @@ +// A port in miniature: it asks something, then prints numbers it drew at +// random. Without a seed those numbers differ on every run, which is what makes +// a program like this impossible to script. +// +// Run by the single-file source launcher, java rng.java, which is the Java +// analogue of go run: no build step, no class file left behind. + +import java.io.BufferedReader; +import java.io.IOException; +import java.io.InputStreamReader; +import java.util.Random; + +public class Rng { + public static void main(String[] arguments) throws IOException { + System.out.print("HOW MANY? "); + System.out.flush(); + + BufferedReader input = new BufferedReader(new InputStreamReader(System.in)); + int count = Integer.parseInt(input.readLine().strip()); + + Random random = new Random(); + StringBuilder drawn = new StringBuilder(); + for (int index = 0; index < count; index++) { + if (index > 0) { + drawn.append(' '); + } + // INT(RND(1) * 1000), the way a port translates it. Written the + // same way in every language here, so a tape gives all of them the + // same numbers. + drawn.append((int) (random.nextDouble() * 1000)); + } + System.out.println(drawn); + } +}