Preserve local validation harnesses and historical source experiments

ChangeLog

@@ -42,6 +42,9 @@
 
 ## Technical changes and Optimizations
 
+- preserve historical local validation helpers, probes and experimental source
+  snapshots as an inactive, checksummed documentation archive
+
 - require ViennaRNA >= 2.7.0 and its logger/prepared-window APIs at configure
   time; install the logger lock for every supported version (PR #267)
 
@@ -138,6 +141,13 @@ energies, restricted partition sums, and trackers.
 ################################################################################  
 ################################################################################
 
+261018 Alexander Mitrofanov
+ * doc/local-validation-archive/, doc/Makefile.am
+   + recover local validation/reproduction scripts and experimental source copies
+   + record original paths and byte hashes without activating archived code
+   * package the corpus as a verified ZIP to preserve long paths in distributions
+   * document why validation artifacts remained outside earlier production commits
+
 261015 Alexander Mitrofanov
  * configure.ac, conda-build-env.yml :
    * require ViennaRNA >= 2.7.0, the first release with vrna_log_lock_set()

doc/Makefile.am

@@ -4,6 +4,9 @@
 ################################################################
 
 EXTRA_DIST =	\
+			local-validation-archive/README.md \
+			local-validation-archive/manifest.json \
+			local-validation-archive/sources.zip \
 			conda.txt \
 			api-documentation.md \
 			build-api.sh \

doc/local-validation-archive/.gitattributes

@@ -0,0 +1 @@
+files/** -whitespace

doc/local-validation-archive/README.md

@@ -0,0 +1,87 @@
+# Recovered local validation artifacts
+
+This archive preserves local research and validation source recovered before
+removing the IntaRNA workspace. It is a historical corpus for review, rather
+than an installed tool or a new prediction implementation. The files are not
+wired into the application build, its tests, or CI.
+
+## Contents and original purpose
+
+The `files/` tree preserves the original workspace-relative layout. It includes
+standalone public-header/installed-library consumers, benchmark drivers,
+configure/dependency probes, archived configure and CI fixtures, native-output comparisons, plotting/report
+helpers, instrumentation patches and alternative source implementations used
+in local measurements. Source snapshots include the abandoned C++17 work,
+a matrix prototype, hash/dense partition experiments, an uncached kinetic
+control, and profiling instrumentation. They are archived rather than
+substituted for current production files.
+
+The source distribution carries these files in `sources.zip`, whose members
+use the original workspace-relative paths. This keeps long historical names
+intact despite the existing distribution tar format's 99-character limit.
+The individual files remain directly reviewable in Git.
+
+`manifest.json` lists every stored file with its original path, byte count,
+SHA-256 and Git blob hash. Copies already reachable from published repository
+refs are omitted. The C++23 audit is proposed separately, as is the six-file
+probability-memory integration port. Delivery payloads, generated build files,
+downloaded dependencies, private correspondence, binaries and large raw data
+are outside this source archive. A separate local recovery archive preserves
+the remaining unique workspace material.
+
+## Why these files were not committed before
+
+These files lived outside the tracked application checkouts, in issue-specific
+validation and profiling directories. They supported earlier PR verification,
+benchmarking and exploratory comparisons, while selected production changes
+were committed separately. Several are deliberately alternate controls or
+instrumented implementations. No file-specific decision record exists for
+every helper; their location and content establish their validation role,
+not that each was an overlooked production fix. They are committed now so
+Martin can inspect that material and the original folder can be removed.
+
+The copied `issue-260-validation/debug-master` header is a pre-finalization
+validation snapshot that omits two includes present in PR #261. Its apparent
+missing documentation files came from sharing a copied `.git` pointer with
+the real worktree; those deletions are not proposed here. The preserved source
+snapshot is inactive and is not a header fix for current master.
+
+## Using the archive
+
+Scripts retain their original paths, assumptions and revision-specific APIs.
+Reconstruct the relevant source revision and dependency environment before
+running them, and use a separate workspace for scripts that edit source files.
+The manifest preserves original bytes, including historical formatting. Its
+scoped Git attribute avoids treating unified-diff context and copied formatting
+as new production whitespace changes.
+
+Python and shell files were checked for syntax when archived. This does not
+certify old experiments against current IntaRNA or reproduce their recorded
+performance. The active memory port has its own release/debug validation PR.
+Historical reports retain their original measurement dates and limitations.
+
+## Original directories
+
+| Directory | Preserved files |
+| --- | ---: |
+| `issue-184-validation` | 4 |
+| `issue-212-validation` | 11 |
+| `issue-244-validation` | 10 |
+| `issue-245-validation` | 6 |
+| `issue-246-validation` | 17 |
+| `issue-257-validation` | 4 |
+| `issue-258-review-validation` | 3 |
+| `issue-258-validation` | 13 |
+| `issue-259-revision-validation` | 8 |
+| `issue-260-validation` | 3 |
+| `issue-262-validation` | 4 |
+| `issue-264-validation` | 5 |
+| `issue-265-validation` | 8 |
+| `issue-267-validation` | 13 |
+| `issue-268-validation` | 8 |
+| `issue-270-anchored-validation` | 4 |
+| `issue-270-validation` | 10 |
+| `issue-274-validation` | 2 |
+| `kinetic-validation` | 9 |
+| `profiling` | 17 |
+| `profiling-default-20260921` | 14 |

doc/local-validation-archive/files/issue-184-validation/build.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -euo pipefail
+validation=/home/alex/CodexProjects/IntaRNA/issue-184-validation
+dependencies=/home/alex/CodexProjects/IntaRNA/issue-246-validation/toolchain
+compiler=/home/alex/CodexProjects/IntaRNA/issue-246-validation/toolchain-gcc14
+source_dir=$1
+mode=$2
+export PATH="$compiler/bin:$PATH"
+export PKG_CONFIG_PATH="$dependencies/lib/pkgconfig"
+export OPENBLAS_NUM_THREADS=1
+cd "$source_dir"
+bash autotools-init.sh > "$validation/logs/$mode-bootstrap.log" 2>&1
+./configure CXX="$compiler/bin/x86_64-conda-linux-gnu-g++" \
+    CC="$compiler/bin/x86_64-conda-linux-gnu-gcc" CPPFLAGS="-I$dependencies/include" \
+    LDFLAGS="-L$dependencies/lib -Wl,-rpath,$dependencies/lib" \
+    --with-boost="$dependencies" --with-boost-libdir="$dependencies/lib" \
+    --with-vrna="$dependencies" --prefix="$validation/install-$mode" \
+    --enable-debug > "$validation/logs/$mode-configure.log" 2>&1
+make -j2 > "$validation/logs/$mode-build.log" 2>&1
+make tests -j2 > "$validation/logs/$mode-tests.log" 2>&1

doc/local-validation-archive/files/issue-184-validation/check-install.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+set -euo pipefail
+validation=/home/alex/CodexProjects/IntaRNA/issue-184-validation
+dependencies=/home/alex/CodexProjects/IntaRNA/issue-246-validation/toolchain
+compiler=/home/alex/CodexProjects/IntaRNA/issue-246-validation/toolchain-gcc14/bin/x86_64-conda-linux-gnu-g++
+prefix="$validation/install-release"
+if test "${1:-all}" != consumer; then
+for header in "$prefix/include/IntaRNA/"*.h; do
+    printf '#include <IntaRNA/%s>\nint main() { return 0; }\n' "$(basename "$header")" > "$validation/header.cpp"
+    "$compiler" -std=c++23 -I"$prefix/include" -I"$dependencies/include" \
+        -fsyntax-only "$validation/header.cpp"
+done
+echo 'All installed public headers compiled independently'
+fi
+cat > "$validation/consumer.cpp" <<'CPP'
+#include <IntaRNA/PredictorEvalOnly.h>
+#include <IntaRNA/AccessibilityDisabled.h>
+#include <IntaRNA/InteractionEnergyBasePair.h>
+#include <IntaRNA/OutputHandlerInteractionList.h>
+INITIALIZE_EASYLOGGINGPP
+int main() {
+    using namespace IntaRNA;
+    RnaSequence t("t", "GG"), q("q", "CC");
+    AccessibilityDisabled a(t, 0, nullptr), b(q, 0, nullptr);
+    ReverseAccessibility reversed(b);
+    InteractionEnergyBasePair energy(a, reversed);
+    OutputHandlerInteractionList output(OutputConstraint(), 10);
+    PredictorEvalOnly eval(energy, output, nullptr,
+        PredictorEvalOnly::parseInteractions("1||&1||", t, q));
+    eval.predict();
+    return output.reported() == 1 && (*output.begin())->energy == -200 ? 0 : 1;
+}
+CPP
+export PKG_CONFIG_PATH="$prefix/lib/pkgconfig:$dependencies/lib/pkgconfig"
+"$compiler" -std=c++23 -DELPP_FEATURE_PERFORMANCE_TRACKING -DELPP_NO_DEFAULT_LOG_FILE "$validation/consumer.cpp" -I"$dependencies/include" \
+    -L"$dependencies/lib" -Wl,-rpath,"$dependencies/lib" \
+    $(pkg-config --cflags --libs IntaRNA) -leasylogging -o "$validation/consumer"
+"$validation/consumer"
+echo 'Installed headers and pkg-config evaluation consumer passed'

doc/local-validation-archive/files/issue-184-validation/consumer.cpp

@@ -0,0 +1,17 @@
+#include <IntaRNA/PredictorEvalOnly.h>
+#include <IntaRNA/AccessibilityDisabled.h>
+#include <IntaRNA/InteractionEnergyBasePair.h>
+#include <IntaRNA/OutputHandlerInteractionList.h>
+INITIALIZE_EASYLOGGINGPP
+int main() {
+    using namespace IntaRNA;
+    RnaSequence t("t", "GG"), q("q", "CC");
+    AccessibilityDisabled a(t, 0, nullptr), b(q, 0, nullptr);
+    ReverseAccessibility reversed(b);
+    InteractionEnergyBasePair energy(a, reversed);
+    OutputHandlerInteractionList output(OutputConstraint(), 10);
+    PredictorEvalOnly eval(energy, output, nullptr,
+        PredictorEvalOnly::parseInteractions("1||&1||", t, q));
+    eval.predict();
+    return output.reported() == 1 && (*output.begin())->energy == -200 ? 0 : 1;
+}

doc/local-validation-archive/files/issue-184-validation/header.cpp

@@ -0,0 +1,2 @@
+#include <IntaRNA/intarna_config.h>
+int main() { return 0; }

doc/local-validation-archive/files/issue-212-validation/build.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -euo pipefail
+validation=/home/alex/CodexProjects/IntaRNA/issue-212-validation
+dependencies=/home/alex/CodexProjects/IntaRNA/issue-246-validation/toolchain
+compiler=/home/alex/CodexProjects/IntaRNA/issue-246-validation/toolchain-gcc14
+source_dir=$1
+mode=$2
+export PATH="$compiler/bin:$PATH"
+export PKG_CONFIG_PATH="$dependencies/lib/pkgconfig"
+export OPENBLAS_NUM_THREADS=1
+cd "$source_dir"
+bash autotools-init.sh > "$validation/logs/$mode-bootstrap.log" 2>&1
+./configure CXX="$compiler/bin/x86_64-conda-linux-gnu-g++" \
+    CC="$compiler/bin/x86_64-conda-linux-gnu-gcc" CPPFLAGS="-I$dependencies/include" \
+    LDFLAGS="-L$dependencies/lib -Wl,-rpath,$dependencies/lib" \
+    --with-boost="$dependencies" --with-boost-libdir="$dependencies/lib" \
+    --with-vrna="$dependencies" --prefix="$validation/install-$mode" \
+    > "$validation/logs/$mode-configure.log" 2>&1
+make -j2 > "$validation/logs/$mode-build.log" 2>&1
+

doc/local-validation-archive/files/issue-212-validation/check-small.py

@@ -0,0 +1,10 @@
+import csv, io, subprocess, json
+b='/home/alex/CodexProjects/IntaRNA/pr-worktrees/issue-212/src/bin/IntaRNA'
+def run(args):
+ p=subprocess.run([b,'--threads=1','--outMode=C','--outCsvCols=start1,end1,start2,end2,E','-n','100','--outDeltaE=100']+args,capture_output=True,text=True)
+ return p.returncode,p.stdout,p.stderr
+for t,q in [('CCCCAAUU','CCGGGGUU'),('CCCAAU','CGGGUU'),('CCCAAUU','CGGGUU'),('CCCAAU','GGGUU'),('CCAAU','GGUU')]:
+ for mode in ('H','M'):
+  for ov in ('N','T','Q'):
+   code,out,err=run(['-t',t,'-q',q,'--seedBP=2','--energy=B','--acc=N','--mode='+mode,'--outOverlap='+ov])
+   print(t,q,mode,ov,out.replace('\n',' / '),err)

doc/local-validation-archive/files/issue-212-validation/distribution-doc/Makefile.am

@@ -0,0 +1,17 @@
+
+################################################################
+# extra files to be added to distribution
+################################################################
+
+EXTRA_DIST =	\
+			analysis/out-overlap.md \
+			analysis/out-overlap/reproduce.py \
+			conda.txt \
+			doxygen.cfg \
+			latex-deps/adjcalc.sty \
+			latex-deps/adjustbox.sty \
+			latex-deps/collectbox.sty \
+			latex-deps/tc-pgf.def \
+			latex-deps/tocloft.sty \
+			latex-deps/trimclip.sty \
+			latex-deps/xtab.sty