Brick Scripts

Node scripts under scripts/ for the Bricks investigation, run from the command line rather than in the browser — sweeps that take too long for a page load, data generators, and reporting/analysis tools. Grouped by what they're for. Other scripts are on Scripts.

Core Brick-Evaluation Engine

The machinery Bricks's pyramid sweeps run on.

• evaluate-bricks-against-board.js — Evaluates every canonical brick against a board (pyramid2 by default) and writes one aggregated results file. Each search stops at 2 solutions by default (proving "fits" is cheap, but proving "doesn't fit" costs the same exhaustive search as full enumeration either way, so stopping early is free); pass --full to enumerate every solution instead. Supports --concurrency (via evaluate-brick-worker.js), resumable checkpointing, and dominance-based inference to skip bricks already settled by an easier or harder one.
• evaluate-brick-worker.js — Worker thread for evaluate-bricks-against-board.js's --concurrency mode. Runs the same evaluateBrick() the sequential path uses, periodically checkpoints an in-progress search to a .partials file so a stopped run resumes instead of restarting hours of work, and reports progress back to the main thread.
• brick-dominance.js — Exploits a partial order over bricks (adding a post or removing a hole can only ever rule placements out, never in) to let one brick's search settle many others without solving them: a brick with no solutions rules out every strictly-harder brick, and a brick with 2+ solutions rules in every strictly-easier one (with a symmetry-based exception). Used by evaluate-bricks-against-board.js to skip bricks whose answer already follows from a solved neighbor.

Elimination Rules & Proofs

Rounds that prove a brick can never have a unique solution, by construction rather than by solving boards directly.

• identify-multi-solution-bricks.js — Proves that certain canonical bricks can never have exactly one solution on any pyramidN board, for every N at once — a genuinely infinite claim no amount of board-sweeping alone could establish. Each rule argues from the boards' own recursive construction (e.g. a half-turn-symmetric top or bottom face, or solutions that always pair up sharing a bottom layer) and writes results/multi-solution-bricks.json.
• square-coverage.js — Given a brick and a 2x2 "square" configuration, reports whether that square lets the brick be eliminated: quarterTurnable/halfTurnable (the square's own post/hole pattern is symmetric enough to admit a second, distinct solution) or untoppable (the layer above can't legally cover the posts it's guaranteed to reach).
• square-coverage-sweep.js — Runs bricks.md's "Square Coverage" Parts 1–3 using square-coverage.js's per-square classifications, writing one results file per Part. A brick is eliminated at a Part when every one of its four square configurations is turnable or untoppable there.
• above-square-holes.js — Given a brick, lists every hole/blank pattern the layer directly above a 2x2 square could present down onto it, by enumerating every way to tile that layer with the brick. Feeds Square Coverage Part 3's "lone fitting square" rule.
• frontier-bottom-layers.js — For every Frontier brick, finds all its pyramid2 solutions and groups them by their bottom layer's own tiling (ignoring how the top layer is filled), flagging bricks where every group is shared by 2+ solutions — candidates for a future elimination rule. Can also derive pyramid3's own bottom-layer groups from that pyramid2 data alone, without a full 3-layer solve. Those pyramid3 results (over 200MB) go in the folder results/frontier-pyramid3-bottom-layers/, split into parts of whole bricks under 20MB each, with an index.json listing them.

Fingerprinting & Layer Groups

The data behind Layer Groups' Fingerprint Directory and bricks.md's Fingerprinting round.

• pyramid-group-catalog.js — Enumerates the space of possible pyramid tilings ("pyramid groups": base families, their reflections, alternating pairs, and corner-flips), computes each one's cumulative bottom-two-layers collision fingerprint, and scores every non-redundant fingerprint by how many Frontier bricks it would eliminate. Writes results/fingerprint-catalog.json, the Fingerprint Directory's own data.
• fingerprint-fits-sweep.js — For every fingerprint in the Fingerprint Directory's narrower PyramidGroup.directoryGroups() survey, sweeps all canonical bricks and records which ones share no collision with it. Writes one results file per fingerprint.
• gen-fingerprint-fits.js — Writes the fits file for each hand-picked fingerprint wired into bricks.md's Fingerprinting round that isn't already covered by fingerprint-fits-sweep.js's own survey — mostly corner-flipped pyramid groups whose fingerprint happens to be a strict superset of their un-flipped parent's.
• fingerprint-overshadow.js — Given a list of fingerprints, reports which ones "overshadow" which others (one's true collisions are a strict subset of another's, so it catches nothing the smaller one doesn't already) — the same test the Fingerprint Directory uses to hide redundant entries.
• frontier-overlap.js — Computes bricks.md's "Frontier" (canonical bricks no round has eliminated yet) and how much it overlaps with each fingerprint's fitting-bricks list. The canonical Node-side source of truth for FINGERPRINTING_HEXES and computeFrontier(), mirrored (not imported) by frontendJS/PageBricks.js for the browser.

Frontier & Funnel Reporting

Turns finished sweep results into the numbers and artifacts bricks.md itself shows.

• bricks-funnel.js — Walks bricks.md's own ## section headers and reports, for each, how many of the 65,536 brick codes are still in the running versus already eliminated by that point — a numbered reconstruction of the page's own elimination funnel.
• cache-singleton-solutions.js — Re-solves every (brick, board) pair a sweep found to have exactly one solution, stopping at the first hit rather than proving there's no second, and writes them all to one file — the data bricks-singletons.md renders as a browsable list.
• generate-pyramid-solution.js — Solves one pyramid board with one brick and writes the first solution found, so bricks.md can show a real, pre-built pyramid without solving one in the browser.

Performance Benchmarking

Measures what the search engine's own optimizations are actually worth.

• benchmark-half-step-offsets.js — Benchmarks the onlyHalfStepOffsets search optimization on pyramid4/pyramid5 by re-running evaluateBrick with and without it on a sample of already-swept bricks, comparing steps, wall time, and — critically — that the verdict itself doesn't change.
• measure-search-performance.js — Measures what each of evaluate-bricks-against-board.js's optimizations (dominance inference, chaining, etc.) is actually worth by replaying a finished sweep's recorded per-brick search times against each strategy, rather than re-solving anything. Writes results/brick-search-performance.json for the "Searching for Bricks" page.