Skip to content

Add behavioural parity gate (closes #8); drop duplicate Python CLI - #9

Merged
pyrex41 merged 1 commit into
mainfrom
parity-gate
Jun 24, 2026
Merged

Add behavioural parity gate (closes #8); drop duplicate Python CLI#9
pyrex41 merged 1 commit into
mainfrom
parity-gate

Conversation

@pyrex41

@pyrex41 pyrex41 commented Jun 24, 2026

Copy link
Copy Markdown
Owner

Summary

Adds the behavioural parity gate requested in #8, and consolidates the CLI on the Go binary by removing the duplicate Python implementation.

Byte-identical kernel.kl across hosts is necessary but not sufficient — the same KL can still execute differently per target (integer width, symbol interning, hash iteration order, memoisation). That gap is what bit shen-cas on shen-rust. This adds an opt-in gate that proves the slice computes the same thing on every target it ships to.

ratatoskr parity PROG OUTDIR

Shakes once, then builds + runs the slice on each stage-2 target twice (two separate boots) and diffs output against a reference (--reference, default lisp) or a committed golden (--expect FILE).

check catches
vs-truth cross-target divergence (the shen-cas case)
two-boot cross-boot nondeterminism
two-pass in-process boot-order nondeterminism (shen-cas#5)

two-pass is target-agnostic via a fixture convention: print two identical passes separated by a line that is exactly ===. Exit 0/1/3 = pass / fail / nothing checkable. --time is advisory.

Verified PASS across all 8 targets:

target   build  vs-truth  two-boot  two-pass
go       ok     ok        ok        ok        425ms
js       ok     ok        ok        ok        73ms
julia    ok     ok        ok        ok        5532ms
lisp     ok     ok        ok        ok        429ms
lua      ok     ok        ok        ok        23ms
rust     ok     ok        ok        ok        1317ms
scheme   ok     ok        ok        ok        445ms
swift    ok     ok        ok        ok        583ms
parity: PASS (8 target(s) checked)

Negative path (corrupt golden → FAIL exit 1 with first-diff) and skip-only path (exit 3) also verified.

Also

  • Fixture: tests/parity.shen + tests/parity.expected (content-addressed memo — the hash/intern axis).
  • Drop duplicate Python CLI: ratatoskr_cli.py, test_portable.py, .github/workflows/portability.yml removed; go.yml already covers the same helpers + embedded builders.json on the 3-OS matrix. Unit tests for the new pure helpers added in parity_test.go. The uvx/pip packaging (pybin/ + pyproject.toml) is kept.
  • Docs: new docs/parity.md; README subcommand table + parity-gate section + cross-platform paragraph rewritten for the Go binary.

Closes #8

🤖 Generated with Claude Code

Byte-identical kernel.kl across hosts is necessary but not sufficient: the
same KL can still execute differently per target (integer width, symbol
interning, hash iteration order, memoisation), so a slice can pass every
byte-identity check and still return wrong, boot-order-dependent answers on
one target. This is the failure shen-cas hit on shen-rust (issue #8).

Add `ratatoskr parity PROG OUTDIR`: shake once, then build + run the slice on
each stage-2 target twice (two separate boots) and diff the output against a
reference (--reference, default lisp) or a committed golden (--expect FILE).
Checks per target: vs-truth (cross-target divergence), two-boot (cross-boot
nondeterminism), and two-pass (in-process boot-order nondeterminism, via the
fixture convention of two identical passes separated by a "===" line).
Exit 0/1/3 = pass / fail / nothing checkable. --time is advisory only.

Fixture: tests/parity.shen + tests/parity.expected — a content-addressed memo
(the hash/intern axis) that is deterministic on correct impls. Verified PASS
across all 8 targets (lisp/lua/go/rust/js/julia/scheme/swift).

Consolidate on the Go binary: remove the duplicate Python CLI (ratatoskr_cli.py,
test_portable.py, the portability workflow) — go.yml already tests the same
cross-platform helpers + embedded builders.json on the 3-OS matrix. The
uvx/pip packaging (pybin/ + pyproject.toml) stays.

Docs: new docs/parity.md; README gets the subcommand, a parity-gate section,
and the cross-platform paragraph rewritten for the Go binary.

Closes #8

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@pyrex41
pyrex41 merged commit 202921d into main Jun 24, 2026
6 checks passed
@pyrex41
pyrex41 deleted the parity-gate branch June 24, 2026 14:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Shaken slice can diverge from reference at runtime per-host; add a behavioral parity gate

1 participant