reveal

# REVEAL.md — Commit–Reveal Protocol (Four-Phase Lifecycle)

See also:

* [SPEC.md](./SPEC.md) (protocol surface and artifact formats)
* [RULES.md](./RULES.md) (participant-facing constraints)
* [PLATFORM.md](./PLATFORM.md) (implementation guidance, diagnostics)
* [ENTRY.md](./ENTRY.md) (post-reveal archival Entry format)

## 1. Purpose

The Reveal protocol ensures that Sequence Dojo problems are:

* **Fair** (no early leakage of setter logic)
* **Verifiable** (hash commitment is meaningful)
* **Educational** (post-competition review is possible)
* **Stable** (results cannot be retroactively altered)

This document defines the four-phase lifecycle of a problem.

---

# 2. Problem Lifecycle Overview

Each problem passes through four distinct phases:

1. **Phase I — Hidden (Active Solving Period)**
2. **Phase II — Freeze (Result Stabilization Period)**
3. **Phase III — Reveal (Public Disclosure & Audit)**
4. **Phase IV — Archive (Permanent Record)**

The Platform enforces all transitions.

Season parameters:

* Time windows and thresholds (e.g., “7 days hidden”, “48 hours freeze”, `K >= 3`) are season-configurable.
* Whatever values are used must be published and stable for the season (and ideally embedded into `published.json.platform` for auditability).

---

# 3. Phase I — Hidden (Active Solving Period)

## 3.1 What is Public

Upon publication, the Platform releases:

* `P_hash` (SHA-256 of canonicalized setter source bytes)
* Disclosure data (default: `a_1, a_3, ..., a_99`)
* `N_check` (default 200)
* Interface specification
* Season environment metadata

The following remain hidden:

* `setter.py`
* Validation logs
* Full ground truth sequence

## 3.2 What is Allowed

* Solvers may submit solutions.
* The Platform judges normally.
* The leaderboard displays:

  * Stage Pass status
  * Reward Correct status
  * Score (if scoring is enabled)
* No setter source code is disclosed.

## 3.3 Minimum Hidden Duration

A problem should remain in Hidden phase for at least (recommended default):

> **7 calendar days**

This ensures:

* Fair independent reasoning
* Meaningful competition window
* No immediate trivialization

---

# 4. Transition to Phase II — Freeze

After the minimum 7-day Hidden period, the Platform evaluates transition conditions.

## 4.1 Transition Conditions

The problem enters Freeze phase if BOTH:

* At least 7 days have passed since publication, AND
* One of the following holds:

  * (A) At least **K ≥ 3** solvers have achieved Reward Correct (200 terms), OR
  * (B) No new Reward Correct submission has appeared for 48 consecutive hours.

This dual condition prevents:

* Premature reveal of difficult problems
* Endless waiting for unsolved problems

---

# 5. Phase II — Freeze (Result Stabilization Period)

## 5.1 Purpose

Freeze phase stabilizes competition results before public reveal.

## 5.2 Effects

During Freeze:

* New solver submissions are no longer accepted.
* The leaderboard is locked.
* No setter code is disclosed.
* Scores are finalized internally.

## 5.3 Duration

Freeze lasts a fixed period (recommended default):

> **48 hours**

This prevents last-minute reveal gaming and ensures leaderboard integrity.

---

# 6. Phase III — Reveal

After Freeze ends, the Platform enters Reveal phase.

## 6.1 What is Published

The Platform must publish:

1. The full `setter.py` source
2. Canonicalization policy used for hashing
3. `P_hash` verification instructions
4. Platform validation logs:

   * Static gate result
   * Sandbox result
   * Runtime measurement
   * Determinism check
5. (Optional) anonymized judging statistics:

   * Number of Stage Pass solvers
   * Number of Reward Correct solvers
   * Branch count (distinct outputs among Stage Pass solvers)

## 6.2 Hash Verification

Any participant must be able to verify:

```
SHA-256(canonicalize(setter.py)) == P_hash
```

If verification fails, the problem is invalid and must be formally reviewed.

## 6.3 Transition to Phase IV — Archive

After Reveal publication, the Platform transitions the problem into an archival state. Archive is not a new secrecy phase; it is a stability and citation phase.

## 6.4 Phase IV — Archive (Permanent Record)

In Archive, the Platform should provide a stable, citable landing page that links:

* the original `published.json`
* the revealed `setter.py` and canonicalization policy
* verification instructions for `P_hash`
* solver statistics (if disclosed)
* an **Entry** document conforming to [ENTRY.md](./ENTRY.md), which acts as the long-term reference record

---

# 7. Solver Code Disclosure (Optional Policy)

The platform may adopt one of three solver disclosure policies:

### Option A — No Solver Reveal (Default Trial)

Only setter source is revealed.

### Option B — Top Solutions Only

Reveal solver programs of:

* All Reward Correct solvers
* Or Top N ranked solvers

### Option C — Full Transparency

Reveal all submitted solver programs (after filtering for safety).

> Recommended for pilot: Option B
> Recommended for mature platform: Option C (with sandbox filtering)

---

# 8. Exceptional Cases

## 8.1 No Solver Achieves Reward Correct

If after 14 days:

* No solver has achieved Reward Correct
* And no new Stage Pass submissions occur for 72 hours

The Platform may:

* Enter Freeze immediately
* Reveal setter code
* Mark the problem as “Unsolved”

## 8.2 Critical Bug in Setter

If a flaw is discovered in the setter program after publication:

* The problem is invalidated
* Scores are voided
* The setter source and bug explanation must be published

---

# 9. Integrity Guarantees

The Reveal protocol ensures:

* Setter cannot alter logic after publication
* Platform cannot retroactively modify problem definition
* Solvers cannot exploit early disclosure
* Community can audit platform honesty

---

# 10. Timeline Example

Example schedule:

| Day    | Event                             |
| ------ | --------------------------------- |
| Day 0  | Problem published (Hidden begins) |
| Day 7  | Minimum Hidden duration reached   |
| Day 8  | 3 solvers reach 200-correct       |
| Day 9  | Freeze begins                     |
| Day 11 | Reveal phase                      |

---

# 11. Versioning

This Reveal protocol is versioned independently of scoring and platform mechanics.

Changes to Reveal rules:

* Must apply only to new problems
* Must not retroactively alter already published problems

Current version: **REVEAL.md v0.1**