feat(qbasic): add MKI$/CVI/MKS$/CVS memory packing built-ins

Implements legacy QBasic's binary packing routines using
strict x86 Little-Endian encoding (DataView API) to faithfully
emulate the IEEE-754 32-bit float and 16-bit signed int layout.

- tokens.js: register MKI$, MKS$, CVI, CVS as built-in identifiers
- builtins.js: pack/unpack via ArrayBuffer + getCharFromCP437 bridge
- tests: unit tests + Truth Vector compliance for round-trip integrity
- builtins_math.json: extend ABS coverage with float formatting

Co-authored-by: Gemini <218195315+gemini-cli@users.noreply.github.com>

Author: jfrelat-lab

src/parser/qbasic/tokens.js

@@ -48,6 +48,7 @@ export const BuiltInTokens = {
     RTRIM$: 'RTRIM$', SPACE$: 'SPACE$', SPC: 'SPC', STRING$: 'STRING$', 
     STR$: 'STR$', HEX$: 'HEX$', RIGHT$: 'RIGHT$', LEFT$: 'LEFT$', MID$: 'MID$', 
     CHR$: 'CHR$', ASC: 'ASC', INSTR: 'INSTR', VAL: 'VAL',
+    MKI$: 'MKI$', MKS$: 'MKS$', CVI: 'CVI', CVS: 'CVS',
 
     // Mathematics
     INT: 'INT', FIX: 'FIX', CINT: 'CINT', RND: 'RND', SIN: 'SIN', 

src/runtime/qbasic/builtins.js

@@ -90,6 +90,57 @@ const executeVAL = (valArg) => {
     return parseFloat(str) || 0;
 };
 
+/**
+ * Emulates MKI$ (Make Integer String).
+ * Packs a 16-bit integer into a 2-byte string using strict x86 Little-Endian order.
+ */
+const executeMKI$ = (val) => {
+    const buffer = new ArrayBuffer(2);
+    // true = Little-Endian encoding (Crucial for MS-DOS compatibility)
+    new DataView(buffer).setInt16(0, Number(val) || 0, true); 
+    const bytes = new Uint8Array(buffer);
+    return getCharFromCP437(bytes[0]) + getCharFromCP437(bytes[1]);
+};
+
+/**
+ * Emulates CVI (Convert to Integer).
+ * Unpacks a 2-byte Little-Endian string back into a 16-bit signed integer.
+ */
+const executeCVI = (str) => {
+    const s = String(str || "");
+    const buffer = new ArrayBuffer(2);
+    const bytes = new Uint8Array(buffer);
+    bytes[0] = s.length > 0 ? getCP437FromChar(s.charAt(0)) : 0;
+    bytes[1] = s.length > 1 ? getCP437FromChar(s.charAt(1)) : 0;
+    return new DataView(buffer).getInt16(0, true);
+};
+
+/**
+ * Emulates MKS$ (Make Single-Precision String).
+ * Packs an IEEE-754 32-bit float into a 4-byte string (Little-Endian).
+ */
+const executeMKS$ = (val) => {
+    const buffer = new ArrayBuffer(4);
+    new DataView(buffer).setFloat32(0, Number(val) || 0, true);
+    const bytes = new Uint8Array(buffer);
+    return getCharFromCP437(bytes[0]) + getCharFromCP437(bytes[1]) + 
+           getCharFromCP437(bytes[2]) + getCharFromCP437(bytes[3]);
+};
+
+/**
+ * Emulates CVS (Convert to Single).
+ * Unpacks a 4-byte string back into a 32-bit float.
+ */
+const executeCVS = (str) => {
+    const s = String(str || "");
+    const buffer = new ArrayBuffer(4);
+    const bytes = new Uint8Array(buffer);
+    for (let i = 0; i < 4; i++) {
+        bytes[i] = s.length > i ? getCP437FromChar(s.charAt(i)) : 0;
+    }
+    return new DataView(buffer).getFloat32(0, true);
+};
+
 /**
  * Sysclone Native Standard Library (STDLIB).
  * Contains pure functions that do not require access to hardware state.
@@ -113,6 +164,10 @@ export const BuiltIns = {
     [BuiltInTokens.ASC]: (str) => getCP437FromChar(String(str).charAt(0) || 0),
     [BuiltInTokens.INSTR]: executeINSTR,
     [BuiltInTokens.VAL]: executeVAL,
+    [BuiltInTokens.MKI$]: executeMKI$,
+    [BuiltInTokens.CVI]: executeCVI,
+    [BuiltInTokens.MKS$]: executeMKS$,
+    [BuiltInTokens.CVS]: executeCVS,
 
     // --- Mathematics ---
     [BuiltInTokens.INT]: (n) => Math.floor(n || 0),

src/runtime/qbasic/builtins.test.js

@@ -7,6 +7,7 @@ import { test, assertEqual, registerSuite } from '../../test_runner.js';
 const { 
     LEN, UCASE$, LCASE$, LTRIM$, RTRIM$, SPACE$, SPC, STRING$, STR$, HEX$, 
     RIGHT$, LEFT$, MID$, CHR$, ASC, INSTR, VAL,
+    MKI$, CVI, MKS$, CVS,
     INT, FIX, CINT, RND, SIN, COS, TAN, ATN, ABS, SQR, EXP, LOG
 } = BuiltIns;
 
@@ -84,6 +85,24 @@ registerSuite('STDLIB: String Built-ins', () => {
         assertEqual(VAL("&O10"), 8, "Should parse octal numbers");
     });
 
+    test('MKI$, CVI, MKS$, CVS Memory Packing (Little-Endian IEEE/Int)', () => {
+        // 16-bit Integer packing (258 = 0x0102)
+        // Little-Endian means Least Significant Byte (02) comes first, then (01).
+        const packedInt = MKI$(258);
+        assertEqual(LEN(packedInt), 2);
+        assertEqual(CVI(packedInt), 258);
+        
+        // Two's complement for negatives (-1 = 0xFFFF)
+        assertEqual(CVI(MKI$(-1)), -1);
+
+        // 32-bit Float packing
+        const packedFloat = MKS$(1.5);
+        assertEqual(LEN(packedFloat), 4);
+        assertEqual(CVS(packedFloat), 1.5);
+        
+        // Fallback for partial string passing
+        assertEqual(CVI(""), 0, "Empty string should safely yield 0");
+    });
 });
 
 registerSuite('STDLIB: Math Built-ins', () => {

src/runtime/qbasic/compatibility.test.js

@@ -85,11 +85,13 @@ registerSuite('Truth Vector: STDLIB: Math & Floating-Point Unit', () => {
 
     test('ABS Function', () => {
         const code = `
-            AbsVal = ABS(-42)
+            AbsInt = ABS(-42)
+            AbsFloatStr$ = LTRIM$(STR$(ABS(-3.14159)))
         `;
         const env = executeToEnv(code);
 
-        assertEqual(env.lookup('AbsVal'), 42, "AbsVal assertion failed");
+        assertEqual(env.lookup('AbsInt'), 42, "AbsInt assertion failed");
+        assertEqual(env.lookup('AbsFloatStr$'), "3.14159", "AbsFloatStr$ assertion failed");
     });
 
     test('SQR Function', () => {
@@ -344,6 +346,34 @@ registerSuite('Truth Vector: STDLIB: Strings & Type Casting', () => {
         assertEqual(env.lookup('NotFoundIdx'), 0, "NotFoundIdx assertion failed");
         assertEqual(env.lookup('OutBoundsIdx'), 0, "OutBoundsIdx assertion failed");
     });
+
+    test('MKI$ and CVI (16-bit Integer Packing)', () => {
+        const code = `
+            PackedStr$ = MKI$(258)
+            Length = LEN(PackedStr$)
+            RestoredPos = CVI(PackedStr$)
+            RestoredNeg = CVI(MKI$(-1))
+        `;
+        const env = executeToEnv(code);
+
+        assertEqual(env.lookup('Length'), 2, "Length assertion failed");
+        assertEqual(env.lookup('RestoredPos'), 258, "RestoredPos assertion failed");
+        assertEqual(env.lookup('RestoredNeg'), -1, "RestoredNeg assertion failed");
+    });
+
+    test('MKS$ and CVS (32-bit Float Packing)', () => {
+        const code = `
+            PackedSng$ = MKS$(1.5)
+            SngLength = LEN(PackedSng$)
+            RestoredSng! = CVS(PackedSng$)
+            RestoredZero! = CVS(MKS$(0))
+        `;
+        const env = executeToEnv(code);
+
+        assertEqual(env.lookup('SngLength'), 4, "SngLength assertion failed");
+        assertEqual(env.lookup('RestoredSng!'), 1.5, "RestoredSng! assertion failed");
+        assertEqual(env.lookup('RestoredZero!'), 0, "RestoredZero! assertion failed");
+    });
 });
 
 registerSuite('Truth Vector: CORE: Control Flow & Jumps', () => {

tests/truth_vectors/qbasic/builtins_math.json

@@ -142,20 +142,23 @@
     {
       "name": "ABS Function",
       "syntax": "ABS(numeric_expression)",
-      "description": "Returns the absolute value of a numeric expression.",
+      "description": "Returns the absolute (positive) value of a numeric expression.",
       "example": {
         "code": [
-          "PRINT ABS(-42)"
+          "PRINT ABS(-42)",
+          "PRINT ABS(3.14)"
         ],
-        "output": " 42 "
+        "output": " 42 \n 3.14 "
       },
       "quirks_and_tests": {
-        "description": "Standard arithmetic absolute conversion.",
+        "description": "Validates absolute arithmetic conversion. Proves that single-precision float formatting is retained by casting the result to a string.",
         "setup": [
-          "AbsVal = ABS(-42)"
+          "AbsInt = ABS(-42)",
+          "AbsFloatStr$ = LTRIM$(STR$(ABS(-3.14159)))"
         ],
         "assertions": [
-          { "var": "AbsVal", "val": 42, "type": "number" }
+          { "var": "AbsInt", "val": 42, "type": "number" },
+          { "var": "AbsFloatStr$", "val": "3.14159", "type": "string", "message": "Must strictly retain the float formatting." }
         ]
       }
     },

tests/truth_vectors/qbasic/builtins_string.json

@@ -363,6 +363,56 @@
           { "var": "OutBoundsIdx", "val": 0, "type": "number" }
         ]
       }
+    },
+    {
+      "name": "MKI$ and CVI (16-bit Integer Packing)",
+      "syntax": "MKI$(integer_expression) / CVI(2_byte_string)",
+      "description": "MKI$ converts a 16-bit signed integer into a 2-byte string using x86 Little-Endian byte order. CVI reverses this process.",
+      "example": {
+        "code": [
+          "PRINT CVI(MKI$(258))"
+        ],
+        "output": " 258 "
+      },
+      "quirks_and_tests": {
+        "description": "CRITICAL QUIRK: Validates strict Little-Endian packing and two's complement for negative numbers. 258 (0x0102) must pack as CHR$(2) + CHR$(1).",
+        "setup": [
+          "PackedStr$ = MKI$(258)",
+          "Length = LEN(PackedStr$)",
+          "RestoredPos = CVI(PackedStr$)",
+          "RestoredNeg = CVI(MKI$(-1))"
+        ],
+        "assertions": [
+          { "var": "Length", "val": 2, "type": "number", "message": "MKI$ must strictly return a 2-byte string." },
+          { "var": "RestoredPos", "val": 258, "type": "number", "message": "CVI must perfectly restore the 16-bit integer." },
+          { "var": "RestoredNeg", "val": -1, "type": "number", "message": "Must respect 16-bit two's complement for negative numbers." }
+        ]
+      }
+    },
+    {
+      "name": "MKS$ and CVS (32-bit Float Packing)",
+      "syntax": "MKS$(single_expression) / CVS(4_byte_string)",
+      "description": "MKS$ converts a single-precision floating-point number into a 4-byte string using IEEE-754 Little-Endian format. CVS reverses this.",
+      "example": {
+        "code": [
+          "PRINT CVS(MKS$(3.14))"
+        ],
+        "output": " 3.14 "
+      },
+      "quirks_and_tests": {
+        "description": "CRITICAL QUIRK: Validates 32-bit floating-point binary packing. Used heavily in demomaking to pack data structures into raw strings.",
+        "setup": [
+          "PackedSng$ = MKS$(1.5)",
+          "SngLength = LEN(PackedSng$)",
+          "RestoredSng! = CVS(PackedSng$)",
+          "RestoredZero! = CVS(MKS$(0))"
+        ],
+        "assertions": [
+          { "var": "SngLength", "val": 4, "type": "number", "message": "MKS$ must strictly return a 4-byte string." },
+          { "var": "RestoredSng!", "val": 1.5, "type": "number", "message": "CVS must perfectly restore the IEEE-754 single precision float." },
+          { "var": "RestoredZero!", "val": 0, "type": "number" }
+        ]
+      }
     }
   ]
 }