DEV Community: Solsticio

Rating Logic Puzzles by the Deductions They Require

Solsticio — Fri, 07 Aug 2026 12:26:46 +0000

Most puzzle generators assign difficulty based on the number of starting clues or the time a brute-force solver takes. Neither metric matches human perception. A grid with few clues might resolve instantly if every move is forced by a simple pattern, while a densely populated board can stall a player who hasn't spotted a specific contradiction. Solsticio, a daily sun/moon logic puzzle, derives its rating from the actual deduction tiers a solver must use to reach a solution.

The problem with counting givens

Counting empty cells assumes that every missing piece adds equal cognitive load. This fails when a puzzle forces a player to chain multiple complex inferences versus a simple scan. Brute-force timing is equally unreliable; it measures machine speed, not human friction. A solver that backtracks aggressively finds a path quickly, but a human relying on logical deduction gets stuck on the same branch.

To align the rating with the player's experience, the generator tracks which specific techniques are required. The system defines four distinct tiers of deduction, ranging from immediate pattern recognition to hypothetical contradiction testing.

export const TIER = {
  TRIO: 1,       // completar trío bloqueado (evitar 3 iguales seguidos)
  BALANCE: 2,    // equilibrio de fila/columna casi llena
  CONNECTOR: 3,  // aplicar conector = / ×
  CONTRA1: 4,    // deducción encadenada por contradicción a 1 paso
};

These tiers are not arbitrary labels. They represent a strict hierarchy of logical complexity. Tier 1 handles local patterns like preventing three identical symbols in a row. Tier 2 manages global balance, ensuring rows and columns do not exceed half the grid size for either symbol. Tier 3 applies connector rules, where adjacent cells with specific relationships force a value. Tier 4 requires assuming a value, propagating consequences, and detecting a contradiction to prove the assumption false.

Separating the sweeps

The solver does not run a monolithic algorithm. Instead, it executes a series of "sweeps," where each pass attempts to fill cells using only one specific technique. This separation is critical for accurate scoring. If a solver mixes techniques in a single pass, it becomes impossible to know which level of logic was actually necessary to solve a specific cell.

Each sweep function iterates through the grid, checking if a cell can be filled solely by its assigned rule. If a cell is filled, the counter for that tier increments. If a sweep detects a contradiction, the solver flags the puzzle as invalid. The logic for Tier 1, which prevents trios of identical symbols, looks like this:

function sweepTrio(cells, n, connIndex) {
  let filled = 0;
  for (let i = 0; i < cells.length; i++) {
    if (cells[i] !== EMPTY) continue;
    const t0 = createsTrio(cells, n, i, 0);
    const t1 = createsTrio(cells, n, i, 1);
    if (t0 && t1) return CONTRA;
    if (t0 === t1) continue; // ninguno o ambos válidos por trío → no fuerza
    const fv = t0 ? 1 : 0;
    if (!localLegal(cells, n, i, fv, connIndex)) return CONTRA;
    cells[i] = fv;
    filled++;
  }
  return filled;
}

// Tier 2 — Equilibrio: un valor excede n/2 en fila/col ⇒ la celda toma el otro.

Notice that sweepTrio returns immediately if it finds a contradiction or if it fills a cell. It does not proceed to check balance or connectors. This isolation ensures that tierCounts accurately reflects the minimum set of tools required to solve the puzzle. The main loop in the solver orchestrates these sweeps in order of increasing complexity.

export function deductiveSolve(puzzle, { maxTier = TIER.CONTRA1 } = {}) {
  const { n, connectors = [] } = puzzle;
  const cells = (puzzle.clues || puzzle.cells).slice();
  const connIndex = buildConnIndex(connectors);
  const tierCounts = { 1: 0, 2: 0, 3: 0, 4: 0 };
  let maxUsed = 0;

  for (;;) {
    if (isComplete(cells)) break;

    let r = sweepTrio(cells, n, connIndex);
    if (r === CONTRA) return fail(cells, maxUsed, tierCounts);
    if (r > 0) { maxUsed = Math.max(maxUsed, 1); tierCounts[1] += r; continue; }

    if (maxTier >= TIER.BALANCE) {
      r = sweepBalance(cells, n, connIndex);
      if (r === CONTRA) return fail(cells, maxUsed, tierCounts);
      if (r > 0) { maxUsed = Math.max(maxUsed, 2); tierCounts[2] += r; continue; }
    }

    if (maxTier >= TIER.CONNECTOR) {
      r = sweepConnector(cells, n, connIndex);
      if (r === CONTRA) return fail(cells, maxUsed, tierCounts);
      if (r > 0) { maxUsed = Math.max(maxUsed, 3); tierCounts[3] += r; continue; }
    }

    if (maxTier >= TIER.CONTRA1) {
      r = sweepContradiction(cells, n, connIndex);
      if (r === CONTRA) return fail(cells, maxUsed, tierCounts);
      if (r > 0) { maxUsed = Math.max(maxUsed, 4); tierCounts[4] += r; continue; }
    }

    break; // atascado: no se puede avanzar solo con deducción hasta maxTier
  }

  return { solved: isComplete(cells), cells, maxTier: maxUsed, tierCounts };
}

The loop continues until the grid is complete or no further progress can be made with the allowed techniques. If the solver gets stuck, it means the puzzle requires a higher tier than currently permitted, or the puzzle is broken. By tracking maxUsed, the system knows exactly which tier was the bottleneck.

Handling the hardest cases

The most difficult puzzles require Tier 4 logic: contradiction. This is where the solver must temporarily assume a value for an empty cell, run the direct propagation rules, and see if that assumption leads to an impossible state. If it does, the original cell must hold the opposite value.

This is computationally more expensive than a simple scan, so the solver isolates it in its own function. It tries one value, runs the direct propagation engine, and checks for a contradiction signal.

function sweepContradiction(cells, n, connIndex) {
  for (let i = 0; i < cells.length; i++) {
    if (cells[i] !== EMPTY) continue;
    for (let v = 0; v < 2; v++) {
      if (!localLegal(cells, n, i, v, connIndex)) continue; // ese valor ya es ilegal por tiers 1-3
      const trial = cells.slice();
      trial[i] = v;
      if (propagateDirect(trial, n, connIndex) === 'contradiction') {
        const fv = 1 - v;
        if (!localLegal(cells, n, i, fv, connIndex)) return CONTRA;
        cells[i] = fv;
        return 1;
      }
    }
  }
  return 0;
}

// ── API pública ──────────────────────────────────────────────────────────────
// Resuelve por deducción pura (sin adivinar). `maxTier` limita la técnica más
// avanzada permitida (para generar niveles de una dificultad acotada).

The propagateDirect function is the engine that drives this check. It runs the Tier 1, 2, and 3 sweeps repeatedly until no more cells can be filled. If this process hits a contradiction, the assumption in the trial grid was wrong.

function propagateDirect(cells, n, connIndex) {
  for (;;) {
    let r = sweepTrio(cells, n, connIndex);
    if (r === CONTRA) return 'contradiction';
    if (r > 0) continue;
    r = sweepBalance(cells, n, connIndex);
    if (r === CONTRA) return 'contradiction';
    if (r > 0) continue;
    r = sweepConnector(cells, n, connIndex);
    if (r === CONTRA) return 'contradiction';
    if (r > 0) continue;
    return 'ok';
  }
}

// Tier 4 — Contradicción a 1 paso: si asumir v en una celda lleva a contradicción
// tras propagación directa, entonces la celda debe ser el otro valor.
// Rellena UNA celda y devuelve (para reiniciar por técnicas más simples después).

This structure allows the difficulty scorer to count exactly how many times a contradiction step was necessary. A puzzle that requires one contradiction is harder than one requiring none, but a puzzle requiring ten contradictions is significantly harder still. The scoring function captures this nuance.

export function scoreDifficulty(solveResult, { n, givenRatio }) {
  const { maxTier, tierCounts } = solveResult;

  let score;
  switch (maxTier) {
    case 0: score = 1; break;              // resuelto sin técnicas (casi todo dado)
    case TIER.TRIO: score = 2; break;      // solo tríos
    case TIER.BALANCE: score = 3; break;   // hasta equilibrio
    case TIER.CONNECTOR: score = 4; break; // requiere conectores
    case TIER.CONTRA1:                     // requiere contradicción encadenada
      score = 5 + Math.min(4, Math.floor((tierCounts[4] - 1) / 3)); // 5..9
      break;
    default: score = 6;
  }

  // Menos pistas ⇒ más difícil; muchas pistas ⇒ más fácil.
  if (givenRatio < 0.32) score += 1;
  if (givenRatio > 0.5) score -= 1;

  return Math.max(1, Math.min(10, score));
}

// Etiqueta legible (para UI / bench).

The score starts at a base determined by the highest tier used. If the puzzle requires Tier 4, the base is 5. It then adds points based on the number of contradiction steps found in tierCounts[4]. Finally, it adjusts the score based on the density of given clues. Fewer clues increase the score, while a high ratio of givens decreases it. The final result is clamped between 1 and 10.

Translating numbers to labels

Raw scores are useful for generation, but players need human-readable labels. The system maps the numeric score to four distinct categories.

export function difficultyLabel(score) {
  if (score <= 2) return 'Fácil';
  if (score <= 4) return 'Medio';
  if (score <= 7) return 'Difícil';
  return 'Experto';
}

A score of 2 or less is "Fácil," indicating the puzzle relies on simple patterns. "Medio" covers the range where balance and connector rules appear. "Difícil" and "Experto" capture the puzzles that force the solver into contradiction territory. This mapping ensures that a player sees "Difícil" only when the generator has confirmed the puzzle requires the specific logical steps associated with that label.

The daily puzzle generation pipeline uses these metrics to filter candidates. It generates a grid, solves it with the tiered solver, and calculates the score. If the score falls outside the target band for the day, the generator discards the grid and tries again. This process guarantees that every daily puzzle matches its intended difficulty, not by guesswork, but by the explicit logical steps a solver must take to finish it.

A daily logic puzzle with no backend at all

Solsticio — Thu, 06 Aug 2026 10:59:54 +0000

I built Solsticio, a daily sun/moon logic puzzle in the
Binairo/Takuzu family, and I set myself one engineering constraint: no backend. The daily
puzzle had to be identical for everyone — on the web, in the Android app, and in the social
videos — without a server deciding anything.

The date is the seed

The whole thing rests on a generator that is deterministic given a seed, and a seed derived
from the date:

export function specForDaily(y, m, d) {
  const base = y * 10000 + m * 100 + d;
  // First seed in [base, base+500) that yields a 6x6 board of difficulty 5..7.
  for (let s = base; s < base + 500; s++) {
    const r = generate({ n: 6, maxTier: TIER.CONTRA1 }, s);
    if (r.ok && r.difficulty >= 5 && r.difficulty <= 7) return { seed: s, n: 6 };
  }
  // Fallbacks: first solvable board, then the base seed itself.
  for (let s = base; s < base + 500; s++) {
    if (generate({ n: 6 }, s).ok) return { seed: s, n: 6 };
  }
  return { seed: base, n: 6 };
}

Same date → same seed → same board, everywhere. No coordination, no database, no clock skew
argument. The scan window exists because not every seed produces a board in the difficulty band
I want, and the fallbacks guarantee the function is total: there is always a puzzle for every
date, even a hypothetical pathological one.

"Solvable" has to mean something specific

A generator that emits a valid board isn't enough. Two extra gates run on every candidate:

Uniqueness by pure deduction. A deductiveSolve pass tries to solve the board using only
inference rules, up to a maximum technique tier. If it can't finish without guessing, the board
is rejected. This is what lets me promise "never guess" — it's not a claim about the puzzle
looking fair, it's a property checked on every board before it ships.

An aesthetics pass. Boards can be functionally valid and still unpleasant: too many givens,
a row that gives itself away, clues clumped in one corner. A separate aestheticsOk check
rejects those. It's the least glamorous part of the generator and the one that most changed how
the game feels.

The difficulty score that specForDaily filters on falls out of the solver: it's the tier of
the hardest technique the solver needed. Difficulty is measured, not assigned.

Two implementations, one algorithm

The generator is written twice: JavaScript for the website and the video pipeline, Dart for the
Flutter app. That's a duplication I'd normally avoid, but sharing a runtime across an Astro
site, a Remotion renderer and a Flutter app costs more than it saves.

The risk with two implementations is drift. If the ports disagree by one bit in the PRNG, the
app and the website show different puzzles on the same day — which breaks the one promise the
product makes. So there's a cross-determinism test that pins the Dart side against reference
vectors captured from the JS prototype: the raw mulberry32 output sequence for a known seed,
plus fully generated levels at several sizes and seeds.

✓ mulberry32(12345) matches the JS sequence
✓ generate() reproduces the JS reference levels 6x6 seed 42
✓ generate() reproduces the JS reference levels 6x6 seed 1
✓ generate() reproduces the JS reference levels 8x8 seed 7
✓ generate() reproduces the JS reference levels 6x6 conn seed 3

Being honest about the gap: that test lives in the app repo and I run it by hand. It is not yet
wired into CI, which means it protects against drift only when I remember to run it. Writing
this post is what made me go look — and it still passes, but "passes when I remember" is not a
guarantee. That's the next thing I'm fixing.

Everything else is a consumer of the same function

The website (Astro on Cloudflare Pages) prerenders one indexable URL per date, in three languages, and rebuilds itself daily in CI so "today" rolls over on its own.
The video pipeline (Remotion) renders a vertical short of the solve animation for each day, in English, Spanish and Portuguese. It uses a different seed offset on purpose, so the video doesn't spoil the actual daily.
The Flutter app computes the same spec locally, which is why it works fully offline.

None of these talk to each other. They just agree, because they compute the same function of
the same date.

Play today's puzzle in the browser: https://solsticio.app/
Free Android app: https://play.google.com/store/apps/details?id=es.cs.solsticio

Happy to go deeper on the solver or the uniqueness check if anyone's interested.