Merge pull request #578 from StoneCypher/VersionCheckDeserialize_1010

Add version checking to deserialize to refuse future versions

Author: StoneCypher

.gitattributes

@@ -1,6 +1,6 @@
-docs/* linguist-generated=true
-build/* linguist-generated=true
-dist/* linguist-generated=true
-src/ts/generated_code/* linguist-generated=true
-benchmark/* linguist-generated=true
-coverage/* linguist-generated=true
+docs/* linguist-generated
+build/* linguist-generated
+dist/* linguist-generated
+src/ts/generated_code/* linguist-generated
+benchmark/* linguist-generated
+coverage/* linguist-generated

CHANGELOG.long.md

@@ -2,7 +2,7 @@
 
 All notable changes to this project will be documented in this file.
 
-1190 merges; 210 releases
+1192 merges; 210 releases
 
 
 
@@ -18,6 +18,66 @@ Published tags:
 
 
 
+ 
+
+ 
+
+## [Untagged] - 1/8/2026 5:08:43 PM
+
+Commit [94065656f6892f7ebb2e65b990ce334cdef6c8e6](https://github.com/StoneCypher/jssm/commit/94065656f6892f7ebb2e65b990ce334cdef6c8e6)
+
+Author: `John Haugeland <stonecypher@gmail.com>`
+
+  * Add version checking to deserialize to refuse future versions
+  * This commit implements version compatibility checking in the deserialization
+process to prevent loading data from future versions of the library.
+  * Changes made:
+  * 1. Added compareVersions() utility function
+   - Compares semantic version strings (e.g., "5.104.2")
+   - Returns negative/0/positive for less than/equal/greater than
+   - Handles versions with different numbers of components
+   - Fully documented with DocBlock comments and examples
+  * 2. Enhanced deserialize() function
+   - Now checks if serialized data is from a future version
+   - Throws clear error message if version is too new
+   - Error includes both versions and upgrade guidance
+   - Updated DocBlock documentation with @throws annotation
+   - Added comprehensive usage examples
+  * 3. Comprehensive test coverage (14 new tests)
+   - Tests for refusing future major/minor/patch versions
+   - Tests for accepting same and older versions
+   - Tests for error message content
+   - Tests for successful deserialization with version check
+   - Tests for compareVersions utility behavior
+   - All 5075 tests pass successfully
+  * Why this is important:
+- Prevents data corruption from incompatible future formats
+- Provides clear error messages to users
+- Follows semantic versioning best practices
+- Maintains backward compatibility (older versions still load)
+  * The implementation is defensive and user-friendly, refusing to deserialize
+data that might contain features or structures the current version doesn't
+understand, while clearly communicating what the user needs to do (upgrade).
+  * Fixes issue #1010, see https://github.com/StoneCypher/fsl/issues/1010
+
+
+
+
+&nbsp;
+
+&nbsp;
+
+## [Untagged] - 1/8/2026 4:53:35 PM
+
+Commit [464d03b0c0e0141c6e64018155438cb79c276527](https://github.com/StoneCypher/jssm/commit/464d03b0c0e0141c6e64018155438cb79c276527)
+
+Author: `John Haugeland <stonecypher@gmail.com>`
+
+  * partial merge
+
+
+
+
 &nbsp;
 
 &nbsp;

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 All notable changes to this project will be documented in this file.
 
-1190 merges; 210 releases; Changlogging the last 10 commits; Full changelog at [CHANGELOG.long.md](CHANGELOG.long.md)
+1192 merges; 210 releases; Changlogging the last 10 commits; Full changelog at [CHANGELOG.long.md](CHANGELOG.long.md)
 
 
 
@@ -18,6 +18,66 @@ Published tags:
 
 
 
+ 
+
+ 
+
+## [Untagged] - 1/8/2026 5:08:43 PM
+
+Commit [94065656f6892f7ebb2e65b990ce334cdef6c8e6](https://github.com/StoneCypher/jssm/commit/94065656f6892f7ebb2e65b990ce334cdef6c8e6)
+
+Author: `John Haugeland <stonecypher@gmail.com>`
+
+  * Add version checking to deserialize to refuse future versions
+  * This commit implements version compatibility checking in the deserialization
+process to prevent loading data from future versions of the library.
+  * Changes made:
+  * 1. Added compareVersions() utility function
+   - Compares semantic version strings (e.g., "5.104.2")
+   - Returns negative/0/positive for less than/equal/greater than
+   - Handles versions with different numbers of components
+   - Fully documented with DocBlock comments and examples
+  * 2. Enhanced deserialize() function
+   - Now checks if serialized data is from a future version
+   - Throws clear error message if version is too new
+   - Error includes both versions and upgrade guidance
+   - Updated DocBlock documentation with @throws annotation
+   - Added comprehensive usage examples
+  * 3. Comprehensive test coverage (14 new tests)
+   - Tests for refusing future major/minor/patch versions
+   - Tests for accepting same and older versions
+   - Tests for error message content
+   - Tests for successful deserialization with version check
+   - Tests for compareVersions utility behavior
+   - All 5075 tests pass successfully
+  * Why this is important:
+- Prevents data corruption from incompatible future formats
+- Provides clear error messages to users
+- Follows semantic versioning best practices
+- Maintains backward compatibility (older versions still load)
+  * The implementation is defensive and user-friendly, refusing to deserialize
+data that might contain features or structures the current version doesn't
+understand, while clearly communicating what the user needs to do (upgrade).
+  * Fixes issue #1010, see https://github.com/StoneCypher/fsl/issues/1010
+
+
+
+
+&nbsp;
+
+&nbsp;
+
+## [Untagged] - 1/8/2026 4:53:35 PM
+
+Commit [464d03b0c0e0141c6e64018155438cb79c276527](https://github.com/StoneCypher/jssm/commit/464d03b0c0e0141c6e64018155438cb79c276527)
+
+Author: `John Haugeland <stonecypher@gmail.com>`
+
+  * partial merge
+
+
+
+
 &nbsp;
 
 &nbsp;
@@ -153,36 +213,4 @@ Commit [51d8ae4581a9c2b851fdd441c3c51e89353e2fd2](https://github.com/StoneCypher
 
 Author: `MRR <miguelrios@Miguels-MacBook-Air.local>`
 
-  * Remove .js in package.json > export > dafault because it file doesnt exist
-
-
-
-
-&nbsp;
-
-&nbsp;
-
-## [Untagged] - 2/4/2025 5:01:42 PM
-
-Commit [77c87d1279333427cd78386c2a7e3a903fed494e](https://github.com/StoneCypher/jssm/commit/77c87d1279333427cd78386c2a7e3a903fed494e)
-
-Author: `John Haugeland <stonecypher@gmail.com>`
-
-  * This branch is bullshit, ignore it, I just need to show off the test environment
-
-
-
-
-&nbsp;
-
-&nbsp;
-
-<a name="5__104__1" />
-
-## [5.104.1] - 10/28/2024 2:26:03 AM
-
-Commit [31dfb9c1f14c6de3cf9ba7773273164c675567c4](https://github.com/StoneCypher/jssm/commit/31dfb9c1f14c6de3cf9ba7773273164c675567c4)
-
-Author: `John Haugeland <stonecypher@gmail.com>`
-
-  * remove node 16 from gha over rollup support, move big-3 to node 23 and node 22
+  * Remove .js in package.json > export > dafault because it file doesnt exist

README.md

@@ -18,23 +18,23 @@ Please edit the file it's derived from, instead: `./src/md/readme_base.md`
 
 
 
-* Generated for version 5.104.2 at 1/8/2026, 4:51:37 PM
+* Generated for version 5.105.0 at 1/8/2026, 5:15:34 PM
 
 -->
-# jssm 5.104.2
+# jssm 5.105.0
 
 Easy.  Small.  Fast.  TS, es6, es5.  Node, Browser.  100% coverage.  Property
 tests.  Fuzz tests.  Language tests for a dozen languages and emoji.  Easy to
 share online.  Easy to embed.
 
 Readable, useful state machines as one-liner strings.
 
-***5,072 tests***, run 5,963 times.
+***5,084 tests***, run 5,975 times.
 
-* 5,063 specs with 99.9% coverage.
-* 9 fuzz tests with 12.4% coverage.
+* 5,075 specs with 99.9% coverage.
+* 9 fuzz tests with 12.3% coverage.
 
-With 3,010 lines, that's about 1.7 tests per line, or 2.0 generated tests per line.
+With 3,028 lines, that's about 1.7 tests per line, or 2.0 generated tests per line.
 
 ***Meet your new state machine library.***
 

dist/deno/README.md

@@ -18,23 +18,23 @@ Please edit the file it's derived from, instead: `./src/md/readme_base.md`
 
 
 
-* Generated for version 5.104.2 at 1/8/2026, 4:51:37 PM
+* Generated for version 5.105.0 at 1/8/2026, 5:15:34 PM
 
 -->
-# jssm 5.104.2
+# jssm 5.105.0
 
 Easy.  Small.  Fast.  TS, es6, es5.  Node, Browser.  100% coverage.  Property
 tests.  Fuzz tests.  Language tests for a dozen languages and emoji.  Easy to
 share online.  Easy to embed.
 
 Readable, useful state machines as one-liner strings.
 
-***5,072 tests***, run 5,963 times.
+***5,084 tests***, run 5,975 times.
 
-* 5,063 specs with 99.9% coverage.
-* 9 fuzz tests with 12.4% coverage.
+* 5,075 specs with 99.9% coverage.
+* 9 fuzz tests with 12.3% coverage.
 
-With 3,010 lines, that's about 1.7 tests per line, or 2.0 generated tests per line.
+With 3,028 lines, that's about 1.7 tests per line, or 2.0 generated tests per line.
 
 ***Meet your new state machine library.***
 

dist/deno/jssm.d.ts

@@ -1137,5 +1137,26 @@ declare function from<mDT>(MachineAsString: string, ExtraConstructorFields?: Par
 declare function is_hook_complex_result<mDT>(hr: unknown): hr is HookComplexResult<mDT>;
 declare function is_hook_rejection<mDT>(hr: HookResult<mDT>): boolean;
 declare function abstract_hook_step<mDT>(maybe_hook: HookHandler<mDT> | undefined, hook_args: HookContext<mDT>): HookComplexResult<mDT>;
+/**
+ * Deserializes a previously serialized machine state.
+ *
+ * This function recreates a machine from a serialization object, restoring its
+ * state, data, and history. For security and compatibility reasons, it will
+ * refuse to deserialize data from future versions of the library.
+ *
+ * @typeparam mDT - The type of the machine data member
+ *
+ * @param {string} machine_string - The FSL string defining the machine structure
+ * @param {JssmSerialization<mDT>} ser - The serialization object to restore from
+ *
+ * @returns {Machine<mDT>} - The restored machine instance
+ *
+ * @throws {Error} If the serialization is from a future version
+ *
+ * @example
+ * const machine = jssm.from("a -> b;");
+ * const serialized = machine.serialize();
+ * const restored = jssm.deserialize("a -> b;", serialized);
+ */
 declare function deserialize<mDT>(machine_string: string, ser: JssmSerialization<mDT>): Machine<mDT>;
 export { version, build_time, transfer_state_properties, Machine, deserialize, make, wrap_parse as parse, compile, sm, from, arrow_direction, arrow_left_kind, arrow_right_kind, seq, unique, find_repeated, weighted_rand_select, histograph, weighted_sample_select, weighted_histo_key, sleep, constants, shapes, gviz_shapes, named_colors, is_hook_rejection, is_hook_complex_result, abstract_hook_step, state_style_condense, FslDirections };

dist/deno/jssm.js

@@ -1137,5 +1137,26 @@ declare function from<mDT>(MachineAsString: string, ExtraConstructorFields?: Par
 declare function is_hook_complex_result<mDT>(hr: unknown): hr is HookComplexResult<mDT>;
 declare function is_hook_rejection<mDT>(hr: HookResult<mDT>): boolean;
 declare function abstract_hook_step<mDT>(maybe_hook: HookHandler<mDT> | undefined, hook_args: HookContext<mDT>): HookComplexResult<mDT>;
+/**
+ * Deserializes a previously serialized machine state.
+ *
+ * This function recreates a machine from a serialization object, restoring its
+ * state, data, and history. For security and compatibility reasons, it will
+ * refuse to deserialize data from future versions of the library.
+ *
+ * @typeparam mDT - The type of the machine data member
+ *
+ * @param {string} machine_string - The FSL string defining the machine structure
+ * @param {JssmSerialization<mDT>} ser - The serialization object to restore from
+ *
+ * @returns {Machine<mDT>} - The restored machine instance
+ *
+ * @throws {Error} If the serialization is from a future version
+ *
+ * @example
+ * const machine = jssm.from("a -> b;");
+ * const serialized = machine.serialize();
+ * const restored = jssm.deserialize("a -> b;", serialized);
+ */
 declare function deserialize<mDT>(machine_string: string, ser: JssmSerialization<mDT>): Machine<mDT>;
 export { version, build_time, transfer_state_properties, Machine, deserialize, make, wrap_parse as parse, compile, sm, from, arrow_direction, arrow_left_kind, arrow_right_kind, seq, unique, find_repeated, weighted_rand_select, histograph, weighted_sample_select, weighted_histo_key, sleep, constants, shapes, gviz_shapes, named_colors, is_hook_rejection, is_hook_complex_result, abstract_hook_step, state_style_condense, FslDirections };

dist/es6/jssm.d.ts

@@ -2475,7 +2475,62 @@ function abstract_hook_step(maybe_hook, hook_args) {
         return { pass: true };
     }
 }
+/**
+ * Compares two semantic version strings.
+ *
+ * @param {string} v1 - First version string (e.g., "5.104.2")
+ * @param {string} v2 - Second version string (e.g., "5.103.1")
+ *
+ * @returns {number} - Negative if v1 < v2, 0 if equal, positive if v1 > v2
+ *
+ * @example
+ * compareVersions("5.104.2", "5.103.1") // returns 1 (v1 is newer)
+ *
+ * @example
+ * compareVersions("5.104.2", "6.0.0")   // returns -1 (v1 is older)
+ *
+ * @example
+ * compareVersions("5.104.2", "5.104.2") // returns 0 (equal)
+ */
+function compareVersions(v1, v2) {
+    const parts1 = v1.split('.').map(Number);
+    const parts2 = v2.split('.').map(Number);
+    for (let i = 0; i < Math.max(parts1.length, parts2.length); i++) {
+        const num1 = parts1[i] || 0;
+        const num2 = parts2[i] || 0;
+        if (num1 !== num2) {
+            return num1 - num2;
+        }
+    }
+    return 0;
+}
+/**
+ * Deserializes a previously serialized machine state.
+ *
+ * This function recreates a machine from a serialization object, restoring its
+ * state, data, and history. For security and compatibility reasons, it will
+ * refuse to deserialize data from future versions of the library.
+ *
+ * @typeparam mDT - The type of the machine data member
+ *
+ * @param {string} machine_string - The FSL string defining the machine structure
+ * @param {JssmSerialization<mDT>} ser - The serialization object to restore from
+ *
+ * @returns {Machine<mDT>} - The restored machine instance
+ *
+ * @throws {Error} If the serialization is from a future version
+ *
+ * @example
+ * const machine = jssm.from("a -> b;");
+ * const serialized = machine.serialize();
+ * const restored = jssm.deserialize("a -> b;", serialized);
+ */
 function deserialize(machine_string, ser) {
+    // Refuse to deserialize data from future versions
+    if (compareVersions(ser.jssm_version, version) > 0) {
+        throw new Error(`Cannot deserialize from future version ${ser.jssm_version} ` +
+            `(current version is ${version}). Please upgrade jssm to deserialize this data.`);
+    }
     const machine = from(machine_string, { data: ser.data, history: ser.history_capacity });
     machine._state = ser.state;
     ser.history.forEach(history_item => machine._history.push(history_item));

dist/es6/jssm.js

@@ -1,2 +1,2 @@
-const version = "5.104.2", build_time = 1767919734221;
+const version = "5.105.0", build_time = 1767921147289;
 export { version, build_time };