fix(research): close replay reference edge cases

Author: erinepshovel-code

research/from-photons-to-macroverse/PREREGISTRATION.md

@@ -139,6 +139,8 @@ standard-normal scalar:     sqrt(-2 ln u_0) * cos(2*pi*u_1)
 
 The displayed formula is explanatory. Its only result-bearing evaluation is the
 fixed-precision implementation and frozen output vectors in the pinned executable;
+when binary64 conversion would round the exact rational to `1.0`, the executable
+uses the greatest binary64 value below one,
 language-native `ln`, `cos`, `sqrt`, `pi`, `tanh`, `softplus`, and Gaussian CDF are
 not replay authorities.
 
@@ -182,7 +184,7 @@ The stream domains are exactly:
 coefficients:        role, tensor_name, carrier_i, carrier_j, row, column
 initial_state:       episode_id, carrier_i, coordinate
 process_noise:       episode_id, phase, phase_time, carrier_id, coordinate
-stability_probe:     attempt, probe_episode, phase, time, carrier_i, coordinate
+stability_probe:     attempt, probe_episode, phase, phase_time, carrier_i, coordinate
 intervention_plan:   episode_id, intervention_class, draw_index
 model_initializers:  model_id, restart, tensor_name, every parameter axis
 minibatch_order:     model_id, restart, update_index, draw_index
@@ -221,9 +223,10 @@ For each `(seed, arity, sigma, generator_role)`, coefficient attempt `a` is
 encoded by appending `/attempt/a` to the coefficient role. Test attempts
 `a=0,...,255` in order. Each attempt is simulated without intervention for the
 `32` burn-in transitions from exactly `16` probe initial states named
-`stability/00` through `stability/15`; their initial-state keys use phase
-`initial` and time `0`, while their noise keys use phase `noise` and the actual
-transition index in the `stability_probe` tuple above. Initial probe normals are
+`stability/00` through `stability/15`. Both use the `stability_probe` domain and
+the executable's complete coefficient-attempt role: initial keys use phase
+`initial` and phase time `0`, while noise keys use phase `noise` and the actual
+transition index in the tuple above. Initial probe normals are
 scaled by `0.10` and noise probe normals by `sigma`, exactly as for dataset
 states and noise. Accept the
 first attempt for which every coordinate of every probe remains in `[-3,3]`
@@ -590,7 +593,9 @@ from the declared full tensor before masking. Treat `v` as a `1 x 2`
 matrix and `h` as a `2 x 1` matrix for those bounds. Active biases start at zero.
 For a model fitted at noise level `sigma`, every active `rho` starts at
 `softplus_inverse(max(sigma^2-1e-6,1e-12))`; inactive entries remain exactly
-zero and never receive an optimizer state. Adam arithmetic and all model,
+zero and never receive an optimizer state. The pinned executable's
+`glorot_initializer_value` and `rho_initializer_value` functions are the sole
+value-producing authority for these initializers. Adam arithmetic and all model,
 adapter, loss, and rollout arithmetic use IEEE-754 binary64.
 
 All families minimize the mean training Gaussian NLL over observational and

research/from-photons-to-macroverse/replay_reference.json

@@ -5,9 +5,9 @@
   "protocol_version": "0.4.0",
   "status": "not-run",
   "reference_path": "tools/replay_reference.py",
-  "reference_sha256": "a4258d2318192477f6e1db6c8b6845104383f43658050e3b598134b67ba2ef70",
-  "contract_sha256": "3f9ca385203effd349a0c03c279cdaa06f357a928849f1c0afd86e61b18236d2",
+  "reference_sha256": "476c3647025adec07d791347c630569679a72f90be20ac579c4d720bd733d9cf",
+  "contract_sha256": "fd8091d81785ec9fb90612a8faa8b31596030fd5ef74c2d547a77d0c1d011cc8",
   "vectors_path": "replay_vectors.json",
-  "vectors_sha256": "ae286e5dca1740e0a3d12a9db22c49523aea877cfb88876b549766597e0740ea",
+  "vectors_sha256": "2bc24cd1be2729f34aa709b7398ea28493adcf51bf344a53b20ee8b0c01861b9",
   "verification_command": "python tools/replay_reference.py verify"
 }

research/from-photons-to-macroverse/replay_vectors.json

@@ -48,7 +48,10 @@
     "complete_path_ascii": "[\"arity-recursion-synthetic-v6\",32,7,50,\"model_initializers\",\"parameter\",[\"direct/7\",0,\"w\",3,5,1,0],0]",
     "complete_path_sha256": "a1361ff6b2df7b177d7d59642032cf93800f9d3529c7855ff8ad1af13e521ce0",
     "different_carrier_sha256": "678465b036832878696515fa8396a5b437f0e7e5be122ff303f4979157a2e93e",
-    "distinct": true
+    "distinct": true,
+    "glorot_f64": "3fd4567787472ab1",
+    "rho_sigma_050_f64": "c017f663be616d7b",
+    "unnested_kind": "direct"
   },
   "minibatch": {
     "draw_key_sha256": "8ef7dab016a249a135928d3b10acd46ed55c84113d9812ac7640defeeccc1884",
@@ -118,8 +121,15 @@
     ]
   },
   "schema": "the-interdependency.arity-recursion-replay-vectors",
+  "stability_probe": {
+    "distinct": true,
+    "initial_ascii": "[\"arity-recursion-synthetic-v6\",32,7,50,\"stability_probe\",\"direct/attempt/0\",[0,\"stability/00\",\"initial\",0,\"3\",1],0]",
+    "noise_ascii": "[\"arity-recursion-synthetic-v6\",32,7,50,\"stability_probe\",\"direct/attempt/0\",[0,\"stability/00\",\"noise\",0,\"3\",1],0]"
+  },
   "stream": {
     "bytes_ascii": "[\"arity-recursion-synthetic-v6\",32,7,50,\"coefficients\",\"direct/attempt/0\",[\"w\",3,5,1,0],0]",
+    "maximum_open_uniform_f64": "3fefffffffffffff",
+    "minimum_open_uniform_f64": "3be0000000000000",
     "normal_f64": "bfd2e86ee75a1753",
     "sha256": "061bd70dc1ffc5f4bb9664eff24fac0c1ec4a53ddfafc5b39b14f3186a29449f",
     "uniform_0_f64": "3f986f5c3707ff18",

research/from-photons-to-macroverse/tests/test_contracts.py

@@ -314,6 +314,10 @@ def test_executable_replay_reference_is_hash_pinned(self) -> None:
             contract["process_noise_phases"], {"burn": [0, 31], "scored": [0, 127]}
         )
         self.assertEqual(contract["training_population_size"], 12288)
+        self.assertEqual(
+            contract["stability_probe_index"],
+            ["attempt", "probe_episode", "phase", "phase_time", "carrier_id", "coordinate"],
+        )
         self.assertEqual(
             contract["variance_head_space"],
             "model output before the fixed observation decoder",
@@ -326,7 +330,20 @@ def test_executable_replay_reference_is_hash_pinned(self) -> None:
 
         vectors = load_json("replay_vectors.json")
         self.assertTrue(vectors["initializer"]["distinct"])
+        self.assertEqual(vectors["initializer"]["unnested_kind"], "direct")
+        self.assertTrue(vectors["stability_probe"]["distinct"])
         self.assertTrue(vectors["noise_phase"]["distinct"])
+        self.assertGreater(replay.open_uniform_word(0), 0.0)
+        self.assertLess(replay.open_uniform_word(2**64 - 1), 1.0)
+        self.assertEqual(
+            replay.f64_hex(replay.rho_initializer_value(50)),
+            vectors["initializer"]["rho_sigma_050_f64"],
+        )
+        self.assertEqual(pin["reference_path"], "tools/replay_reference.py")
+        self.assertEqual(
+            pin["verification_command"],
+            f"python {pin['reference_path']} verify",
+        )
         self.assertEqual(vectors["optimizer"]["tied_restart"], 1)
         self.assertEqual(
             vectors["decision_edges"]["label_shuffle_zero"]["standing"],

research/from-photons-to-macroverse/tools/replay_reference.py

@@ -55,6 +55,7 @@
 PI = Decimal(
     "3.141592653589793238462643383279502884197169399375105820974944592307816406286"
 )
+OPEN_UNIT_MAX = float.fromhex("0x1.fffffffffffffp-1")
 
 HYPOTHESIS_IDS = tuple(
     [f"h_a/{arity}" for arity in DIRECT_ARITIES]
@@ -101,7 +102,10 @@
     "hypothesis_ids": list(HYPOTHESIS_IDS),
     "process_noise_index": ["episode_id", "phase", "phase_time", "carrier_id", "coordinate"],
     "process_noise_phases": {"burn": [0, 31], "scored": [0, 127]},
+    "stability_probe_index": ["attempt", "probe_episode", "phase", "phase_time", "carrier_id", "coordinate"],
     "initializer_index": ["model_id", "restart", "tensor_name", "all_parameter_axes_in_row_major_order"],
+    "initializer_values": "glorot_initializer_value and rho_initializer_value in this executable",
+    "open_uniform_binary64_top": "0x1.fffffffffffffp-1 when exact rational conversion rounds to 1.0",
     "training_population_order": [
         "observational episode ordinal",
         "intervention class 1..4",
@@ -218,14 +222,22 @@ def fdiv(left: float, right: float) -> float:
     return f64(f64(left) / f64(right))
 
 
-def open_uniform(payload: bytes, lane: int = 0) -> float:
-    if lane not in range(4):
-        raise ValueError("lane must be 0..3")
-    word = digest_words(payload)[lane]
+def open_uniform_word(word: int) -> float:
+    """Map one uint64 word to the nearest admitted open binary64 value."""
+
+    if isinstance(word, bool) or not isinstance(word, int) or not 0 <= word < 2**64:
+        raise ValueError("word must be an unsigned 64-bit integer")
     with localcontext() as ctx:
         ctx.prec = 96
         ctx.rounding = ROUND_HALF_EVEN
-        return f64((Decimal(word) + Decimal("0.5")) / (Decimal(2) ** 64))
+        value = f64((Decimal(word) + Decimal("0.5")) / (Decimal(2) ** 64))
+    return OPEN_UNIT_MAX if value >= 1.0 else value
+
+
+def open_uniform(payload: bytes, lane: int = 0) -> float:
+    if lane not in range(4):
+        raise ValueError("lane must be 0..3")
+    return open_uniform_word(digest_words(payload)[lane])
 
 
 def _decimal(value: float | Decimal | int | str) -> Decimal:
@@ -317,6 +329,18 @@ def deterministic_softplus(value: float) -> float:
         return f64((Decimal(1) + x.exp()).ln())
 
 
+def deterministic_softplus_inverse(value: float) -> float:
+    """Inverse softplus under the reference Decimal-to-binary64 contract."""
+
+    if value <= 0:
+        raise ValueError("softplus inverse input must be positive")
+    with localcontext() as ctx:
+        ctx.prec = 96
+        ctx.rounding = ROUND_HALF_EVEN
+        x = _decimal(value)
+        return f64((x.exp() - Decimal(1)).ln())
+
+
 def gaussian_cdf(value: float) -> float:
     """Deterministic standard-normal CDF; tails are frozen at +/-8."""
 
@@ -348,7 +372,7 @@ def family_kind(family_id: str) -> str:
     if family_id.startswith("capacity-only/"):
         return "dense"
     if "/tree" in family_id or family_id.startswith(
-        ("nested/", "wrong-tree/", "outer-cut/", "unnested/")
+        ("nested/", "wrong-tree/", "outer-cut/")
     ):
         return "nested"
     return "direct"
@@ -389,6 +413,46 @@ def initializer_key(
     )
 
 
+def glorot_initializer_value(
+    *,
+    seed: int,
+    arity: int,
+    sigma_milli: int,
+    family_id: str,
+    restart: int,
+    tensor_name: str,
+    axes: Sequence[int],
+    fan_in: int,
+    fan_out: int,
+) -> float:
+    """Return one exact Glorot-uniform initialized matrix scalar."""
+
+    if _uint(fan_in, "fan_in") == 0 or _uint(fan_out, "fan_out") == 0:
+        raise ValueError("Glorot fan sizes must be positive")
+    payload = initializer_key(
+        seed=seed,
+        arity=arity,
+        sigma_milli=sigma_milli,
+        family_id=family_id,
+        restart=restart,
+        tensor_name=tensor_name,
+        axes=axes,
+    )
+    bound = deterministic_sqrt(fdiv(6.0, fadd(fan_in, fan_out)))
+    centered = fsub(fmul(2.0, open_uniform(payload)), 1.0)
+    return fmul(centered, bound)
+
+
+def rho_initializer_value(sigma_milli: int) -> float:
+    """Return the exact raw diagonal-variance initializer for one noise level."""
+
+    if sigma_milli not in NOISE_MILLI:
+        raise ValueError("sigma_milli must be 10, 50, or 100")
+    sigma = fdiv(sigma_milli, 1000)
+    target = max(fsub(fmul(sigma, sigma), 1e-6), 1e-12)
+    return deterministic_softplus_inverse(target)
+
+
 def process_noise_key(
     *,
     seed: int,
@@ -427,6 +491,42 @@ def coefficient_role(system_kind: str, attempt: int, outer: int | None = None) -
     return f"{base}/attempt/{attempt}"
 
 
+def stability_probe_key(
+    *,
+    seed: int,
+    arity: int,
+    sigma_milli: int,
+    system_kind: str,
+    attempt: int,
+    probe_ordinal: int,
+    phase: str,
+    phase_time: int,
+    carrier_id: str,
+    coordinate: int,
+    outer: int | None = None,
+) -> bytes:
+    """Emit one complete stability initial-state or noise scalar key."""
+
+    if not 0 <= probe_ordinal < 16:
+        raise ValueError("probe_ordinal must be 0..15")
+    if phase == "initial":
+        if phase_time != 0:
+            raise ValueError("stability initial state exists only at time 0")
+    elif phase == "noise":
+        if not 0 <= phase_time <= 31:
+            raise ValueError("stability noise time must be 0..31")
+    else:
+        raise ValueError("stability phase must be initial or noise")
+    return stream_bytes(
+        seed=seed,
+        arity=arity,
+        sigma_milli=sigma_milli,
+        domain="stability_probe",
+        role=coefficient_role(system_kind, attempt, outer),
+        indices=[attempt, f"stability/{probe_ordinal:02d}", phase, phase_time, carrier_id, coordinate],
+    )
+
+
 def hypothesis_id(kind: str, arity: int | None = None) -> str:
     if kind == "h_7" and arity is None:
         return "h_7"
@@ -597,6 +697,18 @@ def test_vectors() -> dict[str, object]:
         seed=32, arity=7, sigma_milli=50, family_id="direct/7", restart=0,
         tensor_name="w", axes=[4, 5, 1, 0]
     )
+    glorot_value = glorot_initializer_value(
+        seed=32, arity=7, sigma_milli=50, family_id="direct/7", restart=0,
+        tensor_name="w", axes=[3, 5, 1, 0], fan_in=2, fan_out=2
+    )
+    probe_initial = stability_probe_key(
+        seed=32, arity=7, sigma_milli=50, system_kind="direct", attempt=0,
+        probe_ordinal=0, phase="initial", phase_time=0, carrier_id="3", coordinate=1
+    )
+    probe_noise = stability_probe_key(
+        seed=32, arity=7, sigma_milli=50, system_kind="direct", attempt=0,
+        probe_ordinal=0, phase="noise", phase_time=0, carrier_id="3", coordinate=1
+    )
     burn = process_noise_key(
         seed=32, arity=7, sigma_milli=50, role="direct",
         episode_id="obs/test/000", phase="burn", phase_time=0,
@@ -637,12 +749,22 @@ def test_vectors() -> dict[str, object]:
             "words_hex": [f"{word:016x}" for word in digest_words(payload)],
             "uniform_0_f64": f64_hex(open_uniform(payload, 0)),
             "normal_f64": f64_hex(standard_normal(payload)),
+            "minimum_open_uniform_f64": f64_hex(open_uniform_word(0)),
+            "maximum_open_uniform_f64": f64_hex(open_uniform_word(2**64 - 1)),
         },
         "initializer": {
             "complete_path_ascii": initializer_a.decode("ascii"),
             "complete_path_sha256": hashlib.sha256(initializer_a).hexdigest(),
             "different_carrier_sha256": hashlib.sha256(initializer_b).hexdigest(),
             "distinct": initializer_a != initializer_b,
+            "glorot_f64": f64_hex(glorot_value),
+            "rho_sigma_050_f64": f64_hex(rho_initializer_value(50)),
+            "unnested_kind": family_kind("unnested/7"),
+        },
+        "stability_probe": {
+            "initial_ascii": probe_initial.decode("ascii"),
+            "noise_ascii": probe_noise.decode("ascii"),
+            "distinct": probe_initial != probe_noise,
         },
         "noise_phase": {
             "burn_ascii": burn.decode("ascii"),
@@ -707,6 +829,13 @@ def file_sha256(path: Path) -> str:
 def verify(pin_path: Path) -> dict[str, object]:
     pin = json.loads(pin_path.read_text(encoding="utf-8"))
     here = Path(__file__).resolve()
+    declared_path = pin.get("reference_path")
+    if not isinstance(declared_path, str) or Path(declared_path).is_absolute():
+        raise RuntimeError("reference_path must be one relative path")
+    if (pin_path.parent / declared_path).resolve() != here:
+        raise RuntimeError("reference_path does not resolve to this executable")
+    if pin.get("verification_command") != f"python {declared_path} verify":
+        raise RuntimeError("verification_command does not invoke the pinned executable")
     vectors = test_vectors()
     vectors_path = pin_path.parent / pin["vectors_path"]
     stored_vectors = json.loads(vectors_path.read_text(encoding="utf-8"))