basic pairs construction

README.md

@@ -1065,6 +1065,9 @@ id :: integer? -> id...
 pack :: integer, integer -> id
 unpack :: id -> integer, integer
 
+pair :: id, id -> id
+unpair :: id -> id, id
+
 defer :: boolean
 commit :: boolean
 
@@ -1269,6 +1272,25 @@ function evolved.pack(index, version) end
 function evolved.unpack(id) end
 ```
 
+### `evolved.pair`
+
+```lua
+---@param primary evolved.id
+---@param secondary evolved.id
+---@return evolved.id pair
+---@nodiscard
+function evolved.pair(primary, secondary) end
+```
+
+### `evolved.unpair`
+
+```lua
+---@param pair evolved.id
+---@return evolved.id primary
+---@return evolved.id secondary
+function evolved.unpair(pair) end
+```
+
 ### `evolved.defer`
 
 ```lua

develop/all.lua

@@ -1,6 +1,7 @@
 require 'develop.example'
 require 'develop.untests'
 
+require 'develop.testing.pairs_tests'
 require 'develop.testing.requires_fragment_tests'
 require 'develop.testing.system_as_query_tests'
 

develop/testing/pairs_tests.lua

@@ -0,0 +1,8 @@
+local evo = require 'evolved'
+
+do
+    local p1, s1 = evo.id(2)
+    local pair1 = evo.pair(p1, s1)
+    local p2, s2 = evo.unpair(pair1)
+    assert(p1 == p2 and s1 == s2)
+end

evolved.lua

@@ -771,6 +771,9 @@ local __evolved_id
 local __evolved_pack
 local __evolved_unpack
 
+local __evolved_pair
+local __evolved_unpair
+
 local __evolved_defer
 local __evolved_commit
 
@@ -3914,6 +3917,51 @@ function __evolved_unpack(id)
     return index, version
 end
 
+---@param primary evolved.id
+---@param secondary evolved.id
+---@return evolved.id pair
+---@nodiscard
+function __evolved_pair(primary, secondary)
+    local primary_index = primary % 0x100000
+    local secondary_index = secondary % 0x100000
+
+    if __freelist_ids[primary_index] ~= primary then
+        __error_fmt('the primary id (%s) is not alive and cannot be used',
+            __id_name(primary))
+    end
+
+    if __freelist_ids[secondary_index] ~= secondary then
+        __error_fmt('the secondary id (%s) is not alive and cannot be used',
+            __id_name(secondary))
+    end
+
+    local shifted_secondary = secondary_index * 0x100000
+    return 0 - primary_index - shifted_secondary --[[@as evolved.id]]
+end
+
+---@param pair evolved.id
+---@return evolved.id primary
+---@return evolved.id secondary
+function __evolved_unpair(pair)
+    local primary_index = (0 - pair) % 0x100000
+    local secondary_index = (0 - pair - primary_index) / 0x100000
+
+    local primary = __freelist_ids[primary_index] --[[@as evolved.id]]
+    local secondary = __freelist_ids[secondary_index] --[[@as evolved.id]]
+
+    if primary % 0x100000 ~= primary_index then
+        __error_fmt('the primary id (%s) is not alive and cannot be used',
+            __id_name(primary))
+    end
+
+    if secondary % 0x100000 ~= secondary_index then
+        __error_fmt('the secondary id (%s) is not alive and cannot be used',
+            __id_name(secondary))
+    end
+
+    return primary, secondary
+end
+
 ---@return boolean started
 function __evolved_defer()
     __defer_depth = __defer_depth + 1
@@ -5981,6 +6029,9 @@ evolved.id = __evolved_id
 evolved.pack = __evolved_pack
 evolved.unpack = __evolved_unpack
 
+evolved.pair = __evolved_pair
+evolved.unpair = __evolved_unpair
+
 evolved.defer = __evolved_defer
 evolved.commit = __evolved_commit