Fast8x ablation lab

.github/workflows/ci.yml

@@ -30,6 +30,10 @@ jobs:
       - name: Run Python tests
         run: pytest -q
 
+      - name: Run crypto-analysis quick screens
+        if: runner.os != 'Windows'
+        run: python tests/crypto_analysis/run_all_screens.py --profile quick --variants baseline,fast8x --out /tmp/tricube-quick
+
       - name: CLI smoke
         run: |
           python -m tricube.cli hash --hex 616263

.gitignore

@@ -9,6 +9,10 @@ dist/
 *.egg-info/
 c/build/
 results/tmp/
+tests/crypto_analysis/results/
+paper/*.docx
+paper/*.pdf
+!paper/TriCube_Short_Manuscript_2026-05-20.docx
 *.bin
 *.o
 .DS_Store

CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## Unreleased
+
+Updates preparing the experimental `fast8x` stream path for review.
+
+- Added the opt-in `fast8x` C stream variant and documented its separate
+  domain, round profile, output rate, and benchmark status.
+- Added a fixed `fast8x` seed-123 stream vector and C test coverage for that
+  vector.
+- Added the reproducible crypto-analysis screen suite under `tests/`, with
+  separate screen modules and an all-in-one quick runner.
+- Added CI coverage for C tests, Python tests, and the quick crypto-analysis
+  screen profile on non-Windows runners.
+- Clarified that `fast8x` has been compared against the released TriCube
+  stream baseline in the same C ablation harness, while optimized SHA-2,
+  SHA-3/SHAKE, BLAKE2, and BLAKE3 library comparisons remain future work.
+- Kept `paper/manuscript.md` as the source manuscript and added a short
+  manuscript DOCX under `paper/`.
+
 ## 0.1.0 - 2026-05-19
 
 Initial public repository preparation for TriCube.
@@ -8,5 +26,4 @@ Initial public repository preparation for TriCube.
 - Added Python package with hash, XOF, and deterministic stream APIs.
 - Added fixed test vectors shared by the C and Python paths.
 - Added documentation for design, testing, limitations, comparison, and reproducibility.
-- Added cleaned result summary from the May 2026 internal validation pass.
-
+- Added cleaned result summary from the May 2026 validation pass.

MANIFEST.in

@@ -1,5 +1,6 @@
 include python/README.md
 include LICENSE
+include THIRD_PARTY_NOTICES.md
 include CITATION.cff
 include CHANGELOG.md
 include SECURITY.md
@@ -14,6 +15,7 @@ prune results/raw
 prune benchmarks
 prune tools
 prune examples
+prune experiments
 prune c
 exclude CONTRIBUTING.md
 exclude README.md

README.md

@@ -6,10 +6,23 @@ TriCube is a cryptographic engineering research project, not a secure primitive.
 
 ## Current Status
 
-The repository contains a standalone C11 implementation, a Python reference package, fixed test vectors, CLI tools, benchmarks, reproducibility notes, external-battery run scripts, a cleaned result summary, and a manuscript draft.
+The repository contains a standalone C11 implementation, a Python reference package, fixed test vectors, CLI tools, benchmarks, reproducibility notes, external-battery run scripts, a result summary, and a manuscript.
 
 The strongest current result is that TriCube now has a concrete geometric construction with reproducible C/Python vectors and nontrivial statistical-battery evidence. The main open issues are low-bit PractRand warnings, incomplete cryptanalysis, and performance that is still below mature optimized hash implementations.
 
+## Specification and Security Boundary
+
+The primitive is specified in [docs/specification.md](docs/specification.md). That document gives the public baseline state size, lane layout, tetrahedral decomposition, round transformation, modes, padding, length encoding, domain tags, and test vectors.
+
+The security boundary is in [docs/security-status.md](docs/security-status.md). TriCube has black-box development probes and statistical-battery results, but it does not have formal differential, rotational, algebraic, or reduced-round cryptanalysis. The terms used in this repository are deliberately narrow: a probe or screen is an engineering check for obvious failures, not a security proof.
+
+The reproducible black-box screen suite is in
+[tests/crypto_analysis/](tests/crypto_analysis/). It records the
+exact command, branch, commit, machine, seed, byte count, and status labels for
+each compact run. The same folder also contains a first white-box round-model
+analyzer that checks word-level schedule dependency and coverage without
+claiming formal cryptanalysis.
+
 ## Quick Start
 
 Build and test the C implementation:
@@ -58,10 +71,16 @@ c/build/tricube hash --hex 616263
 c/build/tricube hash path/to/file.bin
 c/build/tricube xof --hex 616263 --bytes 64
 c/build/tricube stream --seed 123 --bytes 1048576 --out stream.bin
+c/build/tricube stream --seed 123 --bytes 1048576 --out stream.bin --variant fast8x
 ```
 
 The public C header is [c/include/tricube.h](c/include/tricube.h). It exposes fixed 256-bit digest mode, XOF mode, context-style update/finalize/squeeze functions, deterministic stream generation, and self-test support.
 
+The experimental `fast8x` stream entry points are kept visible in
+[c/src/tricube_fast8x.c](c/src/tricube_fast8x.c). The shared permutation and
+variant profile live in [c/src/tricube.c](c/src/tricube.c), so `fast8x` remains
+one named TriCube stream variant rather than a forked second implementation.
+
 The Python CLI is available after installation:
 
 ```bash
@@ -77,14 +96,24 @@ TriCube uses 32 lanes of 64 bits each. Twenty-seven lanes correspond to a 3 x 3
 
 Input bytes are absorbed with domain separation and length encoding. Digest mode squeezes 32 bytes. XOF mode squeezes an arbitrary number of bytes. Stream mode initializes from a seed and emits deterministic blocks for statistical testing.
 
+The diagrams in [docs/specification.md](docs/specification.md) show the state
+layout, tetrahedral decomposition, and round flow. The diagrams are explanatory;
+the tables and pseudocode in the specification are the normative source.
+
 The candidate novelty is the cube/tetrahedral state evolution and propagation schedule. It is not the use of hashing, XOFs, ARX operations, or sponge-like absorb/squeeze structure, all of which are established design families.
 
-See [docs/design.md](docs/design.md) for the construction details.
+See [docs/specification.md](docs/specification.md) for the exact construction and [docs/design.md](docs/design.md) for a shorter design overview.
 
 ## Main Results
 
 The following tables summarize the May 2026 validation evidence. These are engineering and statistical-screening results, not security proofs.
 
+The default stream path remains the released baseline. The repository also includes an
+experimental `fast8x` stream variant for external statistical testing. It is
+domain-separated from the baseline and must be requested explicitly with
+`--variant fast8x`. The ablation evidence for that choice is summarized in
+[tests/ablation_lab/](tests/ablation_lab/).
+
 ### Statistical Batteries
 
 | Evaluation | Result | Notes |
@@ -104,38 +133,42 @@ The following tables summarize the May 2026 validation evidence. These are engin
 | Truncated birthday collision checks | PASS | 16/24/32/48/64-bit prefix collision counts were close to birthday expectation under practical sample sizes. |
 | Full-digest collision smoke | PASS | 0 full digest collisions and 0 prefix64 collisions over 20,000 sampled messages. |
 | Message-bit diffusion | PASS | 16-round mean changed bits: 127.819 of 256 over 8,192 samples. |
-| Differential probes | PASS | Across tested deltas and rounds, mean changed bits stayed near 128; no repeated output differences were observed. |
-| Rotational probes | PASS | No exact rotational relation was observed; mean rotational distances stayed near 128 bits. |
+| Black-box differential diffusion probe | PASS | Across tested deltas and rounds, mean changed bits stayed near 128; no repeated output differences were observed. |
+| Black-box rotational relation probe | PASS | No exact rotational relation was observed; mean rotational distances stayed near 128 bits. |
 | Domain/tweak separation | PASS | 5/5 unique digests; minimum hamming distance from default case was 121 bits. |
-| State-recovery screen | PASS | Next-byte prediction accuracy 0.00396061, near the random baseline of 1/256. |
-| Overlap/fork stream test | PASS | 0 repeated 32-byte block overlaps across 4 streams and 262,144 tested blocks. |
+| Black-box state-recovery/predictability screen | PASS | Next-byte prediction accuracy 0.00396061, near the random baseline of 1/256. |
+| Overlap/fork stream uniqueness screen | PASS | 0 repeated 32-byte block overlaps across 4 streams and 262,144 tested blocks. |
+
+These probes are development gates. They do not search differential trails, bound differential probabilities, prove resistance to rotational distinguishers, perform SAT/MILP or Gröbner-basis analysis, or prove state-recovery resistance. See [docs/testing.md](docs/testing.md) for the exact meaning of each probe.
 
 ### Throughput
 
-Stream throughput is usable for external batteries; hash throughput is still the main engineering weakness. Values below are from local May 2026 runs on an Apple M4 Pro Mac mini unless noted.
+Stream throughput is usable for external batteries; hash throughput is still the main engineering weakness. Values below are from May 2026 runs on an Apple M4 Pro Mac mini unless noted.
 
 | Implementation / mode | Throughput |
 |---|---:|
+| Experimental C `fast8x` stream variant | ~132.7 MiB/s |
+| Released C baseline stream in the same ablation harness | ~69.8 MiB/s |
 | `tricube_tc256_xof_fast` stream candidate | ~80.2 MiB/s |
 | `tricube_geo256_chain_fast` stream candidate | ~62.3 MiB/s |
 | `tricube_tetra_block256_chain_fast` stream candidate | ~57.3 MiB/s |
-| Current standalone C TriCube stream | ~51.5 MiB/s in refresh run; ~53.1 MiB/s in local package smoke run |
+| Current standalone C TriCube stream | ~51.5 MiB/s in refresh run; ~53.1 MiB/s in package smoke run |
 | `sha256_counter_chain` Python harness control | ~51.3 MiB/s |
 | Current standalone C TriCube hash, 1024-byte messages, 16 rounds | ~14.7 MiB/s |
 
 These numbers are not a claim of competitiveness with optimized SHA-2, SHA-3, BLAKE2, or BLAKE3 libraries. They identify where the current prototype is usable and where it needs engineering work.
 
 ### Interpretation
 
-TriCube has moved past a sketch: it has a concrete geometric state model, a C implementation, a Python interface, fixed vectors, battery results, structural probes, and reproducible commands. The strongest positive evidence is the TestU01 Crush pass, the Dieharder result with no failures, the absence of obvious structural failures in the current probes, and the fact that the C stream path is fast enough for longer batteries.
+TriCube now has a concrete geometric state model, a C implementation, a Python interface, fixed vectors, battery results, structural probes, and reproducible commands. The strongest positive evidence is the TestU01 Crush pass, the Dieharder result with no failures, the absence of obvious structural failures in the current probes, and the fact that the C stream path is fast enough for longer batteries.
 
 The strongest negative evidence is also clear: PractRand flagged low-bit behavior, cryptanalysis is incomplete, and hash throughput is not yet competitive. The responsible conclusion is that TriCube deserves further review and hardening, not security use.
 
 The full public evidence summary is [results/consolidated-results-2026-05-19.md](results/consolidated-results-2026-05-19.md).
 
 ## Reproducing Results
 
-Quick local checks:
+Quick checks:
 
 ```bash
 make -C c test
@@ -151,28 +184,37 @@ make -C c all
 tools/run_practrand.sh 1073741824
 tools/run_dieharder.sh 1073741824
 tools/run_testu01.sh smallcrush 1073741824
+python benchmarks/bench_stream.py --bytes 268435456 --variants baseline,fast8x --skip-python
 ```
 
 See [tools/run_stat_batteries.md](tools/run_stat_batteries.md), [docs/testing.md](docs/testing.md), and [docs/reproducibility.md](docs/reproducibility.md) before interpreting results.
 
-## Security Limitations
+## Third-Party Tools
+
+TriCube does not bundle SmokeRand, PractRand, Dieharder, TestU01, NIST STS, or
+third-party hash implementations. The scripts in `tools/` assume those
+programs are installed separately and used under their own upstream licenses.
+See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for the public notice table.
 
-TriCube is not secure for production use. The limitations are direct:
+## Analysis Tooling
 
-- no security proof;
-- no independent cryptanalysis;
-- no collision-resistance or preimage-resistance claim;
-- incomplete reduced-round, differential, rotational, algebraic, and state-recovery analysis;
-- unresolved low-bit PractRand warnings;
-- no side-channel or constant-time review;
-- performance is not competitive with mature optimized hashes;
-- statistical batteries do not prove cryptographic security.
+TriCube uses standard external statistical batteries where possible, and the
+next layer of formal analysis should use established solver and algebra systems
+rather than custom ad hoc replacements. Z3, SageMath, CryptoMiniSat,
+CLAASP/CryptoSMT-style frameworks, and related tooling are useful only after a
+verified TriCube reduced-round model exists. The custom work is the TriCube
+model; the search and solving machinery should come from well-understood tools.
+
+The tool plan and optional setup checks are in [docs/tooling.md](docs/tooling.md).
+The current probe definitions and limits are in [docs/testing.md](docs/testing.md).
+
+## Security Limitations
 
-See [docs/security-status.md](docs/security-status.md) and [docs/limitations.md](docs/limitations.md) for the full security boundary.
+TriCube is research-only. It still lacks independent cryptanalysis, formal reduced-round analysis, side-channel review, and complete long-run multi-seed battery campaigns. Statistical batteries and development probes are useful evidence, but they are not a security proof. See [docs/security-status.md](docs/security-status.md) and [docs/limitations.md](docs/limitations.md) for the full boundary.
 
 ## Paper and Citation
 
-The manuscript draft is in [paper/](paper/). It explains where TriCube came from, the current construction, the available evidence, and the analysis still required before stronger claims would be responsible.
+The source manuscript is [paper/manuscript.md](paper/manuscript.md). It explains where TriCube came from, the current construction, the available evidence, and the analysis still required before stronger claims would be responsible. Generated PDF and DOCX exports should be attached to releases rather than tracked as source files.
 
 If you use this repository in research, cite [CITATION.cff](CITATION.cff).
 

THIRD_PARTY_NOTICES.md

@@ -0,0 +1,29 @@
+# Third-Party Notices
+
+TriCube is released under the MIT License. The Python package and wheel do not
+bundle external statistical batteries, third-party cryptographic libraries,
+large result logs, or prebuilt external-tool binaries.
+
+The repository references optional external tools so reviewers can reproduce the
+statistical screening described in the results. Those tools must be installed
+separately and used under their own upstream licenses.
+
+| Tool or project | How TriCube uses it | Bundled in TriCube? | License / source note |
+|---|---|---:|---|
+| SmokeRand | Optional statistical battery referenced in result summaries and reproduction notes. | No | Upstream repository reports MIT License: <https://github.com/alvoskov/SmokeRand>. |
+| PractRand | Optional random-stream statistical testing through `RNG_test`. | No | SourceForge lists PractRand as Public Domain: <https://sourceforge.net/projects/pracrand/>. |
+| Dieharder | Optional random-stream statistical battery through stdin generator mode. | No | Upstream COPYING grants use under GNU GPL v2 or later with the project's stated modification. See <https://github.com/seehuhn/dieharder>. |
+| TestU01 | Optional SmallCrush, Crush, and BigCrush testing through a local stdin wrapper. | No | Current official TestU01-2009 repository reports Apache-2.0: <https://github.com/umontreal-simul/TestU01-2009>. Older archives or mirrors may carry different terms; use the license shipped with the copy you install. |
+| NIST STS | Optional NIST Statistical Test Suite checks. | No | NIST describes the STS software as public domain with a software disclaimer. See <https://csrc.nist.gov/projects/random-bit-generation/documentation-and-software>. |
+| Z3 | Optional SMT solver for future reduced-round bit-vector models. | No | MIT License. See <https://github.com/Z3Prover/z3>. |
+| SageMath | Optional algebraic system for future Boolean polynomial and ANF experiments. | No | GPL-licensed open-source mathematics system. See <https://www.sagemath.org/>. |
+| CryptoMiniSat | Optional SAT solver for future CNF experiments. | No | Upstream project reports default MIT-licensed build material; optional integrations can alter licensing. See <https://github.com/msoos/cryptominisat>. |
+| CLAASP | Optional future framework for automated analysis of symmetric primitives. | No | PyPI metadata lists GPLv3. See <https://pypi.org/project/claasp/> and <https://claasp.readthedocs.io/>. |
+| CryptoSMT | Optional future SMT/SAT cryptanalysis framework. | No | Upstream project: <https://github.com/kste/cryptosmt>. Use the license shipped with the installed copy. |
+| ArxPy | Optional future ARX cryptanalysis framework to investigate. | No | Project documentation: <https://ranea.github.io/ArxPy/>. Use the license shipped with the installed copy. |
+| SHA-2, SHA-3/SHAKE, BLAKE2, BLAKE3, Keccak, CubeHash, Xoodoo/Xoodyak, KangarooTwelve | Referenced for comparison and literature context. | No | These are citations and comparison targets only. TriCube does not copy their implementations. |
+| Python `hashlib` | Used in local benchmark scripts for standard-library comparison. | No separate vendoring | Part of the Python standard library. |
+
+Result logs may mention external tool names, versions, and output summaries.
+Those logs are evidence records only; they are not redistributed copies of the
+external tools.