docs(vrs): measure cross-platform evaluation determinism

CMP-A03 (evaluation is reproducible) said it must be tested rather than
assumed. Tested. A representative plan's canonical serialization is
byte-identical across x86_64-linux, aarch64-linux, and aarch64-darwin —
hash 5160e9b3 on all three. The property several requirements rest on is
now measured, not inferred.

Method: identity is the hash of the evaluated value and transpilation does
not enter it, so the only platform-variable component is the JS engine.
QuickJS-ng's standalone qjs is in nixpkgs, so the engine was exercised
directly via `nix shell nixpkgs#quickjs-ng` on all three arches without
building the pipeline.

Honest surprise, recorded in the experiment: the transcendental Math
functions matched on Apple libm too, so the predicted glibc-vs-Apple
divergence did not reproduce for these inputs on 0.14.0. That does not
refute the primary sources (input- and version-specific) and does not
prove transcendentals agree in general — but it does show the Math lock is
insurance, not a demonstrated-necessary fix. Plan identity is safe because
plans do no such arithmetic at all, not because the lock catches a
divergence about to corrupt a hash.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QzRc44KbA3wfYYKFF9UDMa
agent-session-id: cdf2c185-eeb3-4a4d-8ce0-52885f145cac
agent-tool: Claude Code
agent-tool-version: 2.1.215
agent-model: claude-opus-4-8
agent-runtime-profile: /nix/store/acr8a3l2v366jgmwiq8xdrhgz1py0db5-coding-agent-runtime-profile/share/coding-agents/profile.json
agent-skills-manifest: /nix/store/sj1v5j91h8v8d1w9lca4040302lwrd6v-agent-skills-corpus/share/agent-skills/manifest.json
tooling-profile: dotfiles@unknown-dirty

Author: schickling-assistant

context/.experiments/2026-07-25-cross-platform-evaluation-determinism.md

@@ -0,0 +1,84 @@
+# Cross-platform evaluation determinism
+
+Date: 2026-07-25
+
+Validates the property that a plan's identity is the same on every platform —
+the basis for "same source produces the same version everywhere", which several
+requirements rest on and which had been an inference rather than a measurement.
+
+## Hypothesis
+
+Evaluating a plan produces byte-identical output on x86_64-linux,
+aarch64-linux, and aarch64-darwin, because a plan is pure data construction and
+the only platform-variable surface identified in earlier research —
+libc-delegated transcendental Math — is not reached by a plan and is removed
+from the evaluation global regardless.
+
+## Method
+
+Plan identity is the hash of the evaluated value's canonical serialization, and
+transpilation does not enter identity (0011 Amendment 1), so the only
+platform-variable component is the JavaScript engine. The engine is QuickJS-ng
+(0011), whose standalone interpreter `qjs` is in nixpkgs, so the engine could be
+exercised directly without building the full pipeline.
+
+A probe constructed a representative evaluated plan — nested objects and arrays,
+Unicode and combining-character strings, integer and non-integer arithmetic, and
+integer-like object keys to exercise the key-ordering rule — and printed its
+canonical serialization. As a negative control it also printed the transcendental
+Math functions the design removes from the global, to see whether they were in
+fact a source of cross-platform divergence.
+
+The identical probe ran under `nix shell nixpkgs#quickjs-ng -c qjs` on three
+machines spanning both dimensions that could matter, architecture and libc:
+
+| Machine | Platform |
+| --- | --- |
+| local | x86_64-linux (glibc) |
+| dev4 | aarch64-linux (glibc) |
+| mbp2025 | aarch64-darwin (Apple libm) |
+
+The serialized-plan line was hashed on each and compared.
+
+## Result
+
+The canonical plan serialization was **byte-identical on all three platforms**
+(SHA-256 `5160e9b3…`). The hypothesis holds: a plan's identity does not depend on
+the platform it is evaluated on.
+
+The negative control was more interesting than expected. Every transcendental —
+`sin`, `cos`, `exp`, `log`, `pow`, `tanh` — was **also identical across all
+three**, including on Apple libm. The predicted glibc-vs-Apple-libm divergence
+did not manifest for these inputs on QuickJS-ng 0.14.0.
+
+## Interpretation
+
+The load-bearing conclusion is unaffected and now measured rather than assumed:
+plan identity is platform-independent, because a plan constructs data and touches
+none of the platform-variable surface.
+
+The control result is a genuine discrepancy with the earlier research, which read
+QuickJS-ng master delegating every transcendental straight to libc and cited
+1-ULP glibc/Apple disagreements. Two readings are consistent with both: the
+disagreements are input-specific and these inputs happen to agree, or 0.14.0
+differs from the master source that was read. This experiment does not
+distinguish them, and does **not** establish that transcendentals agree across
+platforms in general — only that they did here.
+
+The Math lock therefore stands as insurance rather than a demonstrated-necessary
+fix: primary sources still show some inputs diverge, a plan has no reason to call
+these functions, and removing them costs three lines. What this experiment
+establishes is that the lock is not load-bearing for plan identity — identity is
+safe because plans do not do arithmetic of this kind at all, not because the lock
+catches a divergence that was about to corrupt a hash.
+
+## Threats to validity
+
+- One probe, one set of Math inputs. A wider input sweep could still surface the
+  predicted transcendental divergence; this experiment did not attempt one,
+  because transcendentals are outside what a plan evaluates.
+- `qjs` is the standalone interpreter, not the embedded `rquickjs` the tool will
+  use. They share the QuickJS-ng core, so engine-level number and string
+  behaviour is the same, but the embedding has not itself been run cross-platform.
+- Darwin coverage is aarch64 only; no x86_64-darwin was tested, and none is in
+  the fleet.

context/requirements.md

@@ -28,7 +28,10 @@ for one layer:
   result on every machine and across engine versions. Agreement about what a
   Plan says — its Steps, their identities, their acceptance — rests on this, so
   it must be tested rather than assumed, and any widening of what evaluation can
-  reach is a change to this assumption.
+  reach is a change to this assumption. Measured across x86_64-linux,
+  aarch64-linux, and aarch64-darwin: a plan's canonical serialization is
+  byte-identical on all three
+  ([experiment](./.experiments/2026-07-25-cross-platform-evaluation-determinism.md)).
 
 ## Acceptable Tradeoffs