Seed repository: rev-8.0.0 reference, frozen oracle, toolchain, test harness

Reference implementation of the strap-beam generators at revision 8.0.0, kept so the acceptance oracle can be regenerated. Not a live target; the running application has no OpenSCAD dependency. The oracle holds 123 frozen cases, 113 accepted and 10 rejected, produced by OpenSCAD 2021.01 with BOSL2 at 92d697c2. The ten rejections are part of the contract: a port that accepts them is wrong. tests/test_oracle.py specifies the port API and was written before the port, so the interface follows from what must be verified rather than what is convenient to implement. Proven by adversarial stub: a build() that rejects everything passes all 10 rejection tests and fails all 226 acceptance tests.
2026-08-18 07:30:17 -05:00
parent eb0d533d86
commit c7e32d8e07
28 changed files with 7822 additions and 1 deletions
@@ -0,0 +1,31 @@
+# Pinned reference toolchain for the rev-8.0.0 acceptance oracle.
+#
+# This image exists for one purpose: regenerating and verifying
+# fixtures/strap-beam-8.0.0/. The running application has no OpenSCAD
+# dependency at all -- see docs/ENVIRONMENT.md section 8.2. Confining OpenSCAD
+# here is why the host's package version cannot drift into the oracle.
+#
+# Do not add anything to this image. Its value is that it contains nothing else.
+
+FROM debian:12-slim
+
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends \
+        openscad \
+        python3 \
+        git \
+        ca-certificates \
+ && rm -rf /var/lib/apt/lists/*
+
+# BOSL2 at the exact commit the oracle was frozen against.
+ARG BOSL2_COMMIT=92d697c2856de2fed93a33e858068589cefc2898
+RUN git clone https://github.com/BelfrySCAD/BOSL2.git /BOSL2 \
+ && git -C /BOSL2 checkout "${BOSL2_COMMIT}" \
+ && rm -rf /BOSL2/.git
+
+# The generators use `include <BOSL2/std.scad>`; OpenSCAD resolves that against
+# OPENSCADPATH after trying the including file's own directory.
+ENV OPENSCADPATH=/
+
+WORKDIR /repo
+CMD ["openscad", "--version"]
@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+#
+# Build the pinned toolchain and prove the committed oracle still reproduces.
+#
+#   ./tools/reference-toolchain/verify.sh          # verify the hash only
+#   ./tools/reference-toolchain/verify.sh --full   # regenerate and compare
+#
+# --full runs all 123 cases through OpenSCAD. On the staging host that takes a
+# while: the solvers are single-threaded and the CPU is old. That is expected.
+
+set -euo pipefail
+
+REPO="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+IMAGE="mechcomp/reference-toolchain:8.0.0"
+EXPECTED="ddd0f1548379205dd0c652ec07285b0dae331e52ff0a0437005dfc6cddcc2cb2"
+
+echo "==> building ${IMAGE}"
+docker build -t "${IMAGE}" "${REPO}/tools/reference-toolchain"
+
+echo
+echo "==> toolchain versions"
+docker run --rm "${IMAGE}" openscad --version
+docker run --rm "${IMAGE}" git -C /BOSL2 rev-parse HEAD 2>/dev/null \
+    || echo "(BOSL2 .git removed at build time; commit is pinned by ARG)"
+
+echo
+echo "==> verifying the committed oracle"
+python3 "${REPO}/fixtures/strap-beam-8.0.0/make_fixtures.py" --verify
+
+if [[ "${1:-}" == "--full" ]]; then
+    echo
+    echo "==> regenerating all 123 cases inside the pinned toolchain"
+    tmp="$(mktemp -d)"
+    trap 'rm -rf "${tmp}"' EXIT
+    cp "${REPO}/fixtures/strap-beam-8.0.0/strap-beam-fixtures-8.0.0.json" "${tmp}/before.json"
+
+    docker run --rm -v "${REPO}:/repo" "${IMAGE}" \
+        python3 /repo/fixtures/strap-beam-8.0.0/make_fixtures.py --regenerate
+
+    echo
+    echo "==> comparing against the committed oracle"
+    if diff -q "${tmp}/before.json" \
+            "${REPO}/fixtures/strap-beam-8.0.0/strap-beam-fixtures-8.0.0.json" >/dev/null; then
+        echo "OK - byte-identical."
+    else
+        echo "DIFFERS from the committed oracle." >&2
+        echo "The 'frozen' date changes on every regeneration, so a one-line" >&2
+        echo "diff there is expected. Any other difference means the toolchain" >&2
+        echo "has drifted; investigate before proceeding." >&2
+        diff "${tmp}/before.json" \
+             "${REPO}/fixtures/strap-beam-8.0.0/strap-beam-fixtures-8.0.0.json" | head -40 >&2
+        cp "${tmp}/before.json" \
+           "${REPO}/fixtures/strap-beam-8.0.0/strap-beam-fixtures-8.0.0.json"
+        echo >&2
+        echo "The committed oracle has been restored. Nothing was overwritten." >&2
+        exit 1
+    fi
+fi
+
+echo
+echo "expected sha256: ${EXPECTED}"