From 5af3200076b72e2f9f19c202ab9d2a7364004017 Mon Sep 17 00:00:00 2001
From: Physick <96335032+DegustatorPonos@users.noreply.github.com>
Date: Sun, 2 Aug 2026 18:37:18 +0500
Subject: V1 puzzle specification

---
 puzzle_specs_v1.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)
 create mode 100644 puzzle_specs_v1.md

(limited to 'puzzle_specs_v1.md')

diff --git a/puzzle_specs_v1.md b/puzzle_specs_v1.md
new file mode 100644
index 0000000..ff9b9bc
--- /dev/null
+++ b/puzzle_specs_v1.md
@@ -0,0 +1,55 @@
+# TEST SPECIFICATION V1
+## Puzzles
+
+1. Termins
+    The field is depicted as `(Data type) Name`
+    u8 is 8-bit integer (uint8_t in C).
+    u32 is a 32-bit integer (uint32_t in C).
+    string is a null-terminated ASCII byte array.
+
+2. Puzzles are stored in binary format. The specification for it is as follows:
+    +----------------------------+---------------+----------------------+
+    | (u8) Specification version | (string) Name | (string) Description |
+    +----------------------------+---------------+----------------------+
+    | (string) Initial code            | (u32) Test count               |
+    +----------------------------------+--------------------------------+
+    |                          (Test) Test value                        |
+    |                                 ...                               |
+    +--------------------------------------+----------------------------+
+    The amount of the tests must be the exact same as specified in test counter.
+
+2. The test is a following struct:
+    +------------------------+---------------------------+-------------------+
+    | (string) Reciever name | (string) Method signature | (u32) Arg counter |
+    +------------------------+---------------------------+-------------------+
+    |                       (Value descriptor) Input value                   |
+    |                                     ...                                |
+    +------------------------------------------------------------------------+
+    |                      (Value descriptor) Expected output                |
+    |                                     ...                                |
+    +------------------------------------------------------------------------+
+    The amount of the input values must be the exact same as specified in arg counter.
+
+4. The value descriptor is a following struct:
+    +----------------+--------------+
+    | (u8) Type code | (Type) Value |
+    +----------------+--------------+
+
+4.1. The type is defined by the Type code. The following types are supported:
+    +------+------+-------------------------------+
+    | Code | Name    | Value size                 |
+    +------+---------+----------------------------+
+    | 0    | Null    | 0 bytes                    |
+    +------+---------+----------------------------+
+    | 1    | Bool    | 1 byte (0 = false)         |
+    +------+---------+----------------------------+
+    | 2    | Num     | 8 bytes                    |
+    +------+---------+----------------------------+
+    | 3    | String  | Variadic, null-terminated  |
+    +------+---------+----------------------------+
+    | 4    | List    | 4 bytes (See the item 3.2) |
+    +------+---------+----------------------------+
+    
+4.2 The list value descriptor contains the amount of elements in the list.
+    The following N Value descriptors will be treated as list elements.
+    That is the only case where the expected output will contain more than one value
-- 
cgit v1.3