fix(space): align SystemOne validation and forced Tetris moves

Signed-off-by: Xunzhuo <Xunzhuo@users.noreply.huggingface.co>

SYSTEM_ONE_MAPPING.md

@@ -12,7 +12,7 @@ Studio exposes a **SystemOne-format Decision service** with official Python SDK
 | `instructions` text/object/array | Required native question text, with the same deterministic JSON rule for structured content. |
 | Choice `criteria` map | Each option name is semantic: null description → name; otherwise name + `: ` + full description. Object insertion order is retained. External native candidate IDs equal the names, but the names reach the model only through this explicit semantic text. |
 | Score `criteria` array | Ordered native levels with IDs and values 0…K−1. Returned score is the probability-weighted level index. |
-| Noul `criteria.false/true` | Native false/true descriptions. If absent, the original native default no/yes descriptions are used. |
+| Noul `criteria.false/true` | Native false/true descriptions. An omitted or `null` description uses the original native default no/yes description. |
 
 The public single-state endpoint requires exactly `model`, `state`, and `questions`, with a 256 KiB JSON body. The separate batch endpoint requires exactly `model`, `states`, and `questions`, with a 2 MiB JSON body and at most 1,024 states, questions, and total decisions. Both accept 2–255 Choice options, 2–10 Score levels, and up to 16 MiB of expanded context/question input. The direct runtime uses a per-model configurable physical microbatch size rather than a fixed eight rows. The complete-input limit is 1,024 tokens for Kai/Lex and 16,384 for Eos/Sol/Nox/Lux **per question**, including state and all candidate descriptions. Unsupported fields and models are rejected.
 

contract.py

@@ -19,9 +19,11 @@ def content(value, label):
     raise ValueError(f"{label} must be text, an object, or an array")
 
 
-def identifier(value, label):
-    if not isinstance(value, str) or not value.strip() or len(value) > 128:
-        raise ValueError(f"{label} must be a nonempty string of at most 128 characters")
+def identifier(value, label, *, max_length=None):
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{label} must be a nonempty string")
+    if max_length is not None and len(value) > max_length:
+        raise ValueError(f"{label} must be at most {max_length} characters")
     return value
 
 
@@ -65,7 +67,7 @@ def _single_records(body, *, model=MODEL):
             if not isinstance(criteria, dict) or set(criteria) - {"false", "true"}:
                 raise ValueError(f"{qid}: Noul criteria accept false and true only")
             for key in ("false", "true"):
-                if key in criteria:
+                if criteria.get(key) is not None:
                     q[key + "_criterion"] = content(criteria[key], qid + ".criteria." + key)
         records.append({"id": f"studio:{index}", "state_text": state, "question": q})
     return records
@@ -132,7 +134,7 @@ def contexts(body, *, model=MODEL):
     for item in states:
         if not isinstance(item, dict) or set(item) != {"id", "state"}:
             raise ValueError("Each context must contain exactly id and state")
-        cid = identifier(item["id"], "Context ID")
+        cid = identifier(item["id"], "Context ID", max_length=128)
         if cid in seen:
             raise ValueError("Context IDs must be unique")
         seen.add(cid)

static/contract.js

@@ -3,7 +3,10 @@
 const object = v => v !== null && typeof v === 'object' && !Array.isArray(v);
 const keys = (value, allowed, label) => { if (!object(value) || Object.keys(value).some(k => !allowed.includes(k))) throw Error(`${label}: unsupported fields or invalid object.`); };
 const content = (v,label) => { if (typeof v === 'string') { if(!v.trim()) throw Error(`${label} must not be empty.`); } else if(!object(v) && !Array.isArray(v)) throw Error(`${label} must be text, an object, or an array.`); };
-const id = (v,label) => { if(typeof v!=='string'||!v.trim()||v.length>128)throw Error(`${label} needs 1–128 characters.`); };
+const id = (v,label,maxLength) => {
+  if(typeof v!=='string'||!v.trim())throw Error(`${label} needs a nonempty string.`);
+  if(maxLength!==undefined&&v.length>maxLength)throw Error(`${label} needs at most ${maxLength} characters.`);
+};
 function finiteJSON(value) {
   if(typeof value==='number'&&!Number.isFinite(value))throw Error('JSON numbers must be finite.');
   if(value && typeof value==='object')Object.values(value).forEach(finiteJSON);
@@ -16,7 +19,7 @@ export function validateRequest(body, expectedModel) {
   if(Object.hasOwn(body,'states')){
     if(!Array.isArray(body.states)||body.states.length<1)throw Error('Provide at least one context.');
     const seen=new Set();
-    for(const row of body.states){keys(row,['id','state'],'Context');id(row.id,'Context ID');if(seen.has(row.id))throw Error('Context IDs must be unique.');seen.add(row.id);content(row.state,`Context ${row.id}`);}
+    for(const row of body.states){keys(row,['id','state'],'Context');id(row.id,'Context ID',128);if(seen.has(row.id))throw Error('Context IDs must be unique.');seen.add(row.id);content(row.state,`Context ${row.id}`);}
   }else content(body.state,'State');
   if(!object(body.questions)||Object.keys(body.questions).length<1)throw Error('Provide at least one named question.');
   for(const[qid,q]of Object.entries(body.questions)) {
@@ -30,7 +33,8 @@ export function validateRequest(body, expectedModel) {
       if(!Array.isArray(q.criteria)||q.criteria.length<2||q.criteria.length>10)throw Error(`${qid}: Score needs 2–10 ordered levels.`);
       q.criteria.forEach(v=>content(v,`${qid} level`));
     } else if(q.criteria!==undefined&&q.criteria!==null) {
-      keys(q.criteria,['false','true'],`${qid} criteria`);Object.values(q.criteria).forEach(v=>content(v,`${qid} criterion`));
+      keys(q.criteria,['false','true'],`${qid} criteria`);
+      Object.values(q.criteria).forEach(v=>{if(v!==null)content(v,`${qid} criterion`);});
     }
   }
   const requestLimit=Object.hasOwn(body,'states')?2*1024*1024:256*1024;

tests/studio_contract.test.mjs

@@ -36,7 +36,7 @@ const answers = {
   urgency: {
     type: 'score',
     score: 1.2,
-    confidence: 0.3,
+    confidence: 0.16,
     legend: { 0: 'Routine', 1: 'Soon', 2: 'Now' },
     probabilities: { 0: 0.2, 1: 0.4, 2: 0.4 },
   },
@@ -75,6 +75,26 @@ test('Choice and Score require instructions and at least two criteria', () => {
   }
 });
 
+test('runtime-compatible nullable Noul criteria and long question labels are accepted', () => {
+  const long = 'q'.repeat(129);
+  const payload = {
+    model: request.model,
+    state: 'A request',
+    questions: {
+      [long]: { type: 'noul', instructions: 'Check this.', criteria: { true: null, false: 'No' } },
+      category: { type: 'choice', instructions: 'Choose.', criteria: { [long]: null, other: null } },
+    },
+  };
+  assert.equal(validateRequest(payload, request.model), payload);
+  assert.throws(() => validateRequest({
+    ...payload,
+    questions: { check: { type: 'noul', instructions: 'Check.', criteria: { true: '' } } },
+  }, request.model));
+  const batch = { ...payload, states: [{ id: 'x'.repeat(129), state: 'A request' }] };
+  delete batch.state;
+  assert.throws(() => validateRequest(batch, request.model));
+});
+
 test('browser request bytes match the single and batch API routes', () => {
   const utf8 = new TextEncoder();
   const questions = { check: { type: 'noul', instructions: 'Check this input.' } };

tests/test_public_api_contract.py

@@ -135,6 +135,30 @@ class PublicAPIContractTests(unittest.TestCase):
             with self.subTest(noul_instructions=instructions), self.assertRaises(ValueError):
                 to_records({"model": MODEL, "state": "A request", "questions": {"decision": question}})
 
+    def test_runtime_compatible_nullable_noul_criteria_and_long_question_names(self):
+        long_name = "q" * 129
+        payload = {
+            "model": CANONICAL,
+            "state": "A request",
+            "questions": {
+                long_name: {
+                    "type": "noul",
+                    "instructions": "Does this need review?",
+                    "criteria": {"true": None, "false": "No review needed"},
+                },
+                "category": {
+                    "type": "choice",
+                    "instructions": "Pick a category.",
+                    "criteria": {"x" * 129: None, "other": None},
+                },
+            },
+        }
+        internal = dict(payload, model=MODEL)
+        records = to_records(internal, model=MODEL)
+        self.assertNotIn("true_criterion", records[0]["question"])
+        self.assertEqual(records[0]["question"]["false_criterion"], "No review needed")
+        self.assertEqual(records[1]["question"]["options"][0]["id"], "x" * 129)
+
 
 if __name__ == "__main__":
     unittest.main()

tests/test_tetris_arena.py

@@ -1,6 +1,7 @@
 import asyncio
 import json
 import unittest
+from unittest.mock import patch
 
 from tetris_arena import (
     LOCAL_MODELS,
@@ -578,12 +579,19 @@ class TetrisArenaTests(unittest.IsolatedAsyncioTestCase):
                 if not legal_placements:
                     continue
                 placements = shortlist_placements(legal_placements, next_piece="T")
+                if len(placements) == 1:
+                    with self.assertRaises(ValueError):
+                        build_decision_request(
+                            board, piece, "T", placements,
+                            LOCAL_MODELS[4].request_model,
+                        )
+                    continue
                 payload, state = build_decision_request(
                     board, piece, "T", placements, LOCAL_MODELS[4].request_model
                 )
                 question = payload["questions"]["placement"]
                 criteria = question["criteria"]
-                self.assertGreaterEqual(len(criteria), 1)
+                self.assertGreaterEqual(len(criteria), 2)
                 self.assertTrue(question["instructions"].strip())
                 largest_choice_count = max(largest_choice_count, len(criteria))
                 self.assertEqual(set(criteria), {placement.id for placement in placements})
@@ -610,6 +618,30 @@ class TetrisArenaTests(unittest.IsolatedAsyncioTestCase):
                 self.assertLessEqual(len(encoded.encode("utf-8")), 1800)
         self.assertEqual(largest_choice_count, 5)
 
+    async def test_single_legal_placement_is_applied_without_invalid_choice_call(self):
+        adapter = RecordingAdapter()
+        original = shortlist_placements
+
+        def one_placement(placements, **kwargs):
+            return original(placements, **kwargs)[:1]
+
+        with patch("tetris_arena.shortlist_placements", side_effect=one_placement):
+            race = await self.manager(adapter).create({
+                "left": LEFT.id,
+                "right": RIGHT.id,
+                "seed": 42,
+                "mode": "steps",
+                "max_steps": 1,
+            })
+            result = await asyncio.wait_for(race.wait(), 1)
+
+        self.assertEqual(adapter.calls, [])
+        self.assertEqual(result["status"], "finished")
+        self.assertEqual(result["results"]["left"]["pieces"], 1)
+        self.assertEqual(result["results"]["right"]["pieces"], 1)
+        self.assertEqual(race.traces["left"][0]["requested_choice"],
+                         race.traces["left"][0]["applied_choice"])
+
     async def test_avoidable_top_out_is_shortlisted_only_after_safe_moves_and_overridden(self):
         game = Game()
         for row in game.board:

tetris_arena.py

@@ -566,25 +566,30 @@ def _orientation(piece: str, rotation: int) -> str:
     return ("up", "right", "down", "left")[rotation % 4]
 
 
-def build_decision_request(
-    game: Game,
-    piece: str,
-    next_piece: str | None,
-    placements: tuple[Placement, ...],
-    model: str | None,
-) -> tuple[dict[str, Any], str]:
-    if not placements:
-        raise ValueError("at least one placement is required")
+def _decision_state(game: Game, piece: str, next_piece: str | None) -> str:
     stats = _board_stats(game.board)
     board = "/".join(game.rows())
     board = "".join("#" if cell != "." else "." for cell in board)
-    state = "; ".join((
+    return "; ".join((
         "Tetris", f"piece={piece}", f"next={next_piece or '?'}",
         f"score={game.score}", f"lines={game.lines}", f"pieces={game.pieces}",
         f"holes={stats.holes}", f"agg={stats.aggregate_height}",
         f"max={stats.max_height}", f"bump={stats.bumpiness}",
         f"heights={','.join(map(str, stats.heights))}", f"board={board}",
     ))
+
+
+def build_decision_request(
+    game: Game,
+    piece: str,
+    next_piece: str | None,
+    placements: tuple[Placement, ...],
+    model: str | None,
+) -> tuple[dict[str, Any], str]:
+    if not 2 <= len(placements) <= 255:
+        raise ValueError("a Choice decision requires 2–255 placements")
+    state = _decision_state(game, piece, next_piece)
+    stats = _board_stats(game.board)
     ordered = sorted(placements, key=lambda option: option.id)
     offset = game.pieces % len(ordered)
     neutral_order = ordered[offset:] + ordered[:offset]
@@ -1372,21 +1377,30 @@ class RaceSession:
                 placements = await asyncio.to_thread(
                     shortlist_placements, legal_placements, next_piece=next_piece
                 )
-                request, state = build_decision_request(
-                    game,
-                    piece,
-                    next_piece,
-                    placements,
-                    competitor.request_model,
-                )
+                request = None
+                if len(placements) == 1:
+                    # A single legal move is not a Choice decision. Apply it
+                    # directly so strict providers do not reject the turn.
+                    state = _decision_state(game, piece, next_piece)
+                else:
+                    request, state = build_decision_request(
+                        game,
+                        piece,
+                        next_piece,
+                        placements,
+                        competitor.request_model,
+                    )
                 before = game.public()
                 legal_choices = frozenset(placement.id for placement in placements)
                 try:
-                    outcome = await self.adapter.decide(
-                        competitor,
-                        request,
-                        legal_choices,
-                    )
+                    if request is None:
+                        outcome = DecisionOutcome(
+                            choice=placements[0].id, request_ms=0.0
+                        )
+                    else:
+                        outcome = await self.adapter.decide(
+                            competitor, request, legal_choices
+                        )
                 except ArenaUpstreamError as exc:
                     status = "error"
                     reason = "provider_error"