spec

# Sequence Dojo — Submission & Publication Protocol (SPEC) (Draft v0.3)

This document is the protocol surface for Sequence Dojo: artifact formats, required interfaces, and what the Platform must publish and later reveal.

See also:

* [RULES.md](./RULES.md) (participant-facing constraints)
* [REVEAL.md](./REVEAL.md) (lifecycle phases and disclosure)
* [PLATFORM.md](./PLATFORM.md) (implementation guidance for gates and sandboxing)
* [SCORING.md](./SCORING.md) (ranking among correct solvers)

This document defines a **platform-enforced** workflow for publishing Sequence Dojo problems under a **Commit–Reveal** protocol. The core idea is simple:

* **Setters submit code + metadata to the Platform**
* The **Platform validates** safety, determinism, and performance
* Only then does the Platform **publish the problem statement + platform-generated hash**
* After judging ends, the Platform **reveals the setter code** so anyone can verify the hash

The protocol is designed to eliminate:

* “Simulated”/self-reported hashes
* transcription errors in disclosed data
* unsafe or non-deterministic setter programs
* manual copy/paste failures in solver submissions

---

# 1. Roles

### Setter

Creates a hidden deterministic program that generates an integer sequence.

### Solver

Infers the hidden logic from disclosed terms and submits a program that generates the first 200 terms.

### Platform (Judge)

Validates submissions, generates commitments (hashes), publishes problems, runs judging, and performs reveal.

---

# 2. Submission Package (Setter → Platform)

A setter submits a **package** (directory or zip) containing at minimum:

## 2.1 `problem.json` (metadata)

Example:

```json
{
  "title": "Trial 002",
  "author": "setter_handle",
  "version": "1.0",
  "interface": "seq",
  "N_check": 200,
  "reveal_policy": "after_judged",
  "notes": "pure function, deterministic, no I/O",
  "expected_runtime_ms": 100
}
```

**Required fields**

* `title`: human-readable name
* `interface`: `"seq"` or `"gen"`
* `N_check`: integer (default 200)

**Optional fields**

* `author`, `version`, `notes`, `expected_runtime_ms`
* `reveal_policy`: `"after_judged"` (default) or other platform-defined options

## 2.2 `setter.py` (the generator)

The setter must implement **exactly one** of the following interfaces:

### Interface A (recommended)

```python
def seq(n: int) -> int:
```

### Interface B

```python
def gen(N: int) -> list[int]:
```

Return values must be Python `int`. For invalid inputs, it should raise an exception.

---

# 3. Mandatory Constraints (Setter Program)

The setter program must satisfy all constraints below.

## 3.1 Pure Function & Determinism

The program must not:

* read/write files
* access the network
* spawn subprocesses
* read system time / clock
* read environment variables or any external state

Randomness is allowed **only if deterministic**, i.e. a fixed seed is hard-coded such that output is fully reproducible.

## 3.2 Dependency Whitelist

Allowed imports:

* `sympy`, `math`, `fractions`, `itertools`

Disallowed imports include (not exhaustive):

* `os`, `pathlib`, `subprocess`, `socket`, `requests`, `time`, `datetime`

The Platform enforces this via static scanning and runtime import interception.

## 3.3 Resource Limits

* Must generate `a_0..a_{N_check-1}` within **1 second** on the Platform standard machine
* Code length ≤ **100 lines** (Platform-defined “effective code lines”)
* Total UTF-8 character count ≤ **5000** (including whitespace and newlines)

---

# 4. Platform Validation Gates (Publish Allowed Only After Passing)

The Platform must perform the following checks before publishing any problem.

## Gate A — Static Validation

* Measure effective lines and character count (must pass)
* Parse AST and reject disallowed imports/symbols
* Reject obviously dangerous primitives (platform-defined), typically including:

  * `open`, `eval`, `exec`, `compile`, `__import__`

## Gate B — Sandbox Safety Validation

Execute `setter.py` in a restricted sandbox:

* block filesystem access
* block network access
* block subprocess creation
* enforce import whitelist at runtime

Any violation fails the submission.

## Gate C — Performance Validation

Run the setter to compute `a[0..N_check-1]`.

* Total runtime must be ≤ 1 second
* Platform may record runtime/memory metrics for later analytics

## Gate D — Determinism Validation

Run the same generation at least twice in the same environment.

* Outputs must match exactly, element by element
* Any nondeterminism fails the submission

---

# 5. Canonicalization & Platform Commitment (Hash)

**Setters must not self-report hashes.**

The Platform produces the hash after canonicalizing the source.

## 5.1 Canonicalization Rules

The Platform canonicalizes `setter.py` into bytes by:

* forcing UTF-8 encoding
* normalizing all line endings to `\n`
* removing trailing empty lines at end-of-file
* leaving line-trailing whitespace unchanged

## 5.2 Commitment Hash

The Platform computes:

* `P_hash = SHA-256(canonical_setter_py_bytes)`

This `P_hash` is the official commitment.

---

# 6. Publication Output (Platform → Public)

After passing Gates A–D, the Platform publishes a **public problem record**, e.g. `published.json`:

```json
{
  "problem_id": "<sha256>",
  "title": "Trial 002",
  "P_hash": "<sha256>",
  "interface": "seq",
  "N_check": 200,
  "disclosure": {
    "type": "odd_first_50",
    "values": ["<a_1>", "<a_3>", "...", "<a_99>"]
  },
  "timestamp": "2026-02-13T00:00:00Z"
}
```

`problem_id` is the stable public identifier and is required to equal `P_hash` (the commitment hash). The two fields are
kept distinct in the schema to preserve conceptual clarity, but the Platform must enforce equality.

## 6.1 Disclosure Data (No Manual Copy/Paste)

The Platform must generate disclosure values directly from the validated setter output.
For the default rule `odd_first_50`, the disclosure is:

* `[a_1, a_3, …, a_99]`

This eliminates transcription errors.

---

# 7. Solver Submissions (Solver → Platform)

To prevent copy/paste errors, the Platform accepts **only program submissions** as official solutions.

A solver submits:

* `solver.py`
* optional `solution.json` (notes, approach)

### Required interface (recommended)

```python
def solver() -> list[int]:
```

The function must return exactly `N_check` integers (`200` by default), representing:

* `[a_0, a_1, …, a_{N_check-1}]`

Alternatively, the Platform may allow `seq/gen` interfaces, but it must be fixed per season.

## 7.1 Solver Constraints

The Platform should enforce the same safety/determinism constraints for solver code as for setter code (at minimum: no I/O, no network, no subprocess).

---

# 8. Judging Rules

The Platform computes ground truth from the setter:

* `a_true = [a_0..a_199]`

It computes the solver output:

* `a_hat = solver()`

The result is judged by exact equality.

## 8.1 Stage Pass & Reward

* **Stage Pass**: first 100 terms match exactly
  `a_hat[0:100] == a_true[0:100]`
* **Reward**: first 200 terms match exactly
  `a_hat[0:200] == a_true[0:200]`

The Platform should report:

* pass/fail
* earliest mismatch index (if any)
* expected vs. actual value at mismatch

---

# 9. Reveal Policy (After Judging)

Once the problem is closed (or after judging ends), the Platform reveals:

* the full `setter.py` source
* the canonicalization policy
* (optionally) runtime and determinism check logs

Anyone can verify that:

* `SHA-256(canonical(setter.py)) == P_hash`

---

# 10. Platform Transparency Requirements

For reproducibility, the Platform must publicly fix and disclose:

* Python version and relevant library versions (e.g., sympy)
* standard machine class/spec
* timing method (wall time vs CPU time)
* effective line-count rule and character-count rule
* canonicalization policy used for hashing

These must remain stable for at least a full season.

---

# 11. Non-Compliance

A setter submission is rejected (not published) if it violates any constraint or fails any gate.

A solver submission is rejected if it violates sandbox rules, fails to return properly formatted output, or exceeds resource limits.

The Platform may rate-limit or suspend repeat offenders.

---

## Appendix A — Recommended Folder Layout

Setter package:

```
trial-002/
  problem.json
  setter.py
```

Solver package:

```
solution/
  solver.py
  solution.json   (optional)
```