iscc-lib 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 715e7aff39d5570a55f1bde98bd6c8c477152c870b9eff2f3e83a0e3744a100c
-  data.tar.gz: 6f13f0a34d8adc6eb90e1aebc2dabca0cf8112207a749ca39d992d25b8687470
+  metadata.gz: 50fc883dc45f0160658cce96aca449059dcd83f1cd5a344c6254659e0214370c
+  data.tar.gz: cde84cb2f3bff34d8c0ae0bdeda3d2064dc852e3055fcfb2e3dff207240a5848
 SHA512:
-  metadata.gz: e0b35d6acd961e3ab9450f18d09ad8c943a3292e3d2cc3ac57dcf25b38b720f4554bd315ac6a71287ef1d7793acf2961efccbc40ecdeb08ab7af026b52f85dc9
-  data.tar.gz: 41f08243ccffbabab385911994c6dc5784b49476f8263691c6ae6104f45f432785d50265a9f80ce961d89d5f0c5495c4ad5bcc34903847c142cbd3493cb588a8
+  metadata.gz: b96e334c9c24acd5261bdc5d619f7eb92f606a496fe2b59389e76e4c6da0bfa3775969e48d42253921300d7cd3290725fa9975bdb69087cfed0eabadc78fab62
+  data.tar.gz: 449a1ca2f2d40441fcb871ce67b5fe7b45f61a7a08b14d774dcb5a6dd636ca5994fde435fa73ed0bb67abedf3f90cebcea970a8126e5a29ed888bfc16c926cd9

data/lib/iscc_lib/version.rb

@@ -2,5 +2,5 @@
 
 # Version constant for the iscc-lib gem (synced from root Cargo.toml).
 module IsccLib
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/lib/iscc_lib.rb

@@ -63,6 +63,9 @@ module IsccLib
   # Result from gen_sum_code_v0.
   class SumCodeResult < Result; end
 
+  # Result from gen_iscc_id_v1.
+  class IdCodeResult < Result; end
+
   # Generate a Meta-Code from name and optional metadata.
   #
   # @param name [String] content name (required, non-empty)
@@ -157,6 +160,21 @@ module IsccLib
     SumCodeResult[_gen_sum_code_v0(path, bits, wide, add_units)]
   end
 
+  # Generate an ISCC-IDv1 from a timestamp and a HUB-ID (experimental).
+  #
+  # Packs a 52-bit microsecond UTC timestamp and a 12-bit HUB-ID into an
+  # ISCC-ID unit with realm as SubType and Version V1. There is no dedicated
+  # decoder — use iscc_decode to decode.
+  #
+  # @param timestamp [Integer] microsecond UTC timestamp (0 <= timestamp < 2^52)
+  # @param hub_id [Integer] HUB-ID (0 <= hub_id < 4096)
+  # @param realm [Integer] realm (0 = testnet, 1 = mainnet)
+  # @return [IdCodeResult] hash with iscc
+  # @raise [RuntimeError] if any parameter is negative or out of range
+  def self.gen_iscc_id_v1(timestamp, hub_id, realm)
+    IdCodeResult[_gen_iscc_id_v1(timestamp, hub_id, realm)]
+  end
+
   # Streaming Data-Code generator (reopens native class).
   #
   # Incrementally processes data with content-defined chunking and MinHash

data/src/lib.rs

@@ -4,10 +4,10 @@
 //! under the `IsccLib` module. The pure Ruby wrapper in `lib/iscc_lib.rb`
 //! provides idiomatic result classes and keyword arguments.
 //!
-//! Symbols (32 of 32):
+//! Symbols (33 of 33):
 //! - `gen_meta_code_v0`, `gen_text_code_v0`, `gen_image_code_v0`, `gen_audio_code_v0`
 //! - `gen_video_code_v0`, `gen_mixed_code_v0`, `gen_data_code_v0`
-//! - `gen_instance_code_v0`, `gen_iscc_code_v0`, `gen_sum_code_v0`
+//! - `gen_instance_code_v0`, `gen_iscc_code_v0`, `gen_sum_code_v0`, `gen_iscc_id_v1`
 //! - `text_clean`, `text_remove_newlines`, `text_trim`, `text_collapse`
 //! - `encode_base64`, `iscc_decompose`, `encode_component`, `iscc_decode`
 //! - `json_to_data_url`, `conformance_selftest`
@@ -17,12 +17,15 @@
 //! - Constants: META_TRIM_NAME, META_TRIM_DESCRIPTION, META_TRIM_META,
 //!   IO_READ_SIZE, TEXT_NGRAM_SIZE
 
-use magnus::{Error, RArray, RHash, RString, Ruby, TryConvert, function, method, prelude::*};
+use magnus::{
+    Error, Integer, RArray, RHash, RString, Ruby, TryConvert, function, method, prelude::*,
+};
 use std::cell::RefCell;
 
 /// Map an `IsccError` to a Magnus `RuntimeError`.
 fn to_magnus_err(e: iscc_lib::IsccError) -> Error {
-    Error::new(magnus::exception::runtime_error(), e.to_string())
+    let ruby = Ruby::get().expect("called from Ruby");
+    Error::new(ruby.exception_runtime_error(), e.to_string())
 }
 
 /// Generate a Meta-Code from name and optional metadata.
@@ -187,6 +190,55 @@ fn gen_sum_code_v0(path: String, bits: u32, wide: bool, add_units: bool) -> Resu
     Ok(hash)
 }
 
+/// Validate an ISCC-IDv1 parameter before narrowing to a fixed-width integer.
+///
+/// Ruby Integers are arbitrary precision, so each parameter is taken as a
+/// `magnus::Integer` and range-checked here — converting in the signature
+/// would raise `RangeError` during argument marshalling for values beyond
+/// `i64`, breaking the normative `timestamp -> hub_id -> realm` first-failure
+/// order. Rejects negative and out-of-range (`>= max_exclusive`) values with
+/// a `RuntimeError` so an invalid Ruby Integer raises instead of being
+/// silently narrowed to a wrong ID.
+fn checked(value: Integer, max_exclusive: u64, name: &str) -> Result<u64, Error> {
+    let ruby = Ruby::get().expect("called from Ruby");
+    let v = value.to_u64().map_err(|_| {
+        Error::new(
+            ruby.exception_runtime_error(),
+            format!("Invalid {name}: out of range"),
+        )
+    })?;
+    if v >= max_exclusive {
+        return Err(Error::new(
+            ruby.exception_runtime_error(),
+            format!("Invalid {name}: {v}"),
+        ));
+    }
+    Ok(v)
+}
+
+/// Generate an ISCC-IDv1 from a timestamp and a HUB-ID (experimental).
+///
+/// Packs a 52-bit microsecond UTC `timestamp` into the high bits and a 12-bit
+/// `hub_id` (0-4095) into the low bits, encoding the result as an ISCC-ID unit
+/// with `realm` (0 = testnet, 1 = mainnet) as SubType and Version `V1`. The
+/// three semantic thresholds are validated in `timestamp` → `hub_id` → `realm`
+/// order before narrowing, so the first failing check wins.
+///
+/// Returns a Ruby Hash with key: `iscc`. Raises `RuntimeError` if any parameter
+/// is negative, or if `timestamp >= 2^52`, `hub_id >= 2^12`, or `realm` is not
+/// `0` or `1` — for any Integer magnitude, including values beyond `i64`.
+fn gen_iscc_id_v1(timestamp: Integer, hub_id: Integer, realm: Integer) -> Result<RHash, Error> {
+    let timestamp = checked(timestamp, 1u64 << 52, "timestamp")?;
+    let hub_id = checked(hub_id, 4096, "hub_id")?;
+    let realm = checked(realm, 2, "realm")?;
+    let r =
+        iscc_lib::gen_iscc_id_v1(timestamp, hub_id as u16, realm as u8).map_err(to_magnus_err)?;
+    let ruby = Ruby::get().expect("called from Ruby");
+    let hash = ruby.hash_new();
+    hash.aset("iscc", r.iscc)?;
+    Ok(hash)
+}
+
 /// Clean and normalize text for display.
 ///
 /// Applies NFKC normalization, removes control characters (except newlines),
@@ -265,7 +317,7 @@ fn iscc_decode(iscc: String) -> Result<RArray, Error> {
     arr.push(st)?;
     arr.push(vs)?;
     arr.push(li)?;
-    arr.push(RString::from_slice(&digest))?;
+    arr.push(ruby.str_from_slice(&digest))?;
     Ok(arr)
 }
 
@@ -307,7 +359,8 @@ fn alg_simhash(hash_digests: RArray) -> Result<RString, Error> {
         })
         .collect::<Result<Vec<_>, Error>>()?;
     let result = iscc_lib::alg_simhash(&digests).map_err(to_magnus_err)?;
-    Ok(RString::from_slice(&result))
+    let ruby = Ruby::get().expect("called from Ruby");
+    Ok(ruby.str_from_slice(&result))
 }
 
 /// Compute a 256-bit MinHash digest from 32-bit integer features.
@@ -315,7 +368,8 @@ fn alg_simhash(hash_digests: RArray) -> Result<RString, Error> {
 /// Returns a 32-byte binary String.
 fn alg_minhash_256(features: Vec<u32>) -> RString {
     let result = iscc_lib::alg_minhash_256(&features);
-    RString::from_slice(&result)
+    let ruby = Ruby::get().expect("called from Ruby");
+    ruby.str_from_slice(&result)
 }
 
 /// Split data into content-defined chunks using gear rolling hash.
@@ -330,7 +384,7 @@ fn alg_cdc_chunks(data: RString, utf32: bool, avg_chunk_size: u32) -> Result<RAr
     let ruby = Ruby::get().expect("called from Ruby");
     let arr = ruby.ary_new_capa(chunks.len());
     for chunk in chunks {
-        arr.push(RString::from_slice(chunk))?;
+        arr.push(ruby.str_from_slice(chunk))?;
     }
     Ok(arr)
 }
@@ -348,7 +402,8 @@ fn soft_hash_video_v0(frame_sigs: RArray, bits: u32) -> Result<RString, Error> {
         })
         .collect::<Result<Vec<_>, Error>>()?;
     let result = iscc_lib::soft_hash_video_v0(&frames, bits).map_err(to_magnus_err)?;
-    Ok(RString::from_slice(&result))
+    let ruby = Ruby::get().expect("called from Ruby");
+    Ok(ruby.str_from_slice(&result))
 }
 
 /// Streaming Data-Code generator for Ruby.
@@ -372,10 +427,11 @@ impl RbDataHasher {
     ///
     /// Raises `RuntimeError` if called after `finalize`.
     fn update(&self, data: RString) -> Result<(), Error> {
+        let ruby = Ruby::get().expect("called from Ruby");
         let mut inner = self.inner.borrow_mut();
         let hasher = inner.as_mut().ok_or_else(|| {
             Error::new(
-                magnus::exception::runtime_error(),
+                ruby.exception_runtime_error(),
                 "DataHasher already finalized",
             )
         })?;
@@ -391,14 +447,14 @@ impl RbDataHasher {
     /// Returns an `RHash` with key `"iscc"`. Raises `RuntimeError` if
     /// called more than once.
     fn finalize(&self, bits: u32) -> Result<RHash, Error> {
+        let ruby = Ruby::get().expect("called from Ruby");
         let hasher = self.inner.borrow_mut().take().ok_or_else(|| {
             Error::new(
-                magnus::exception::runtime_error(),
+                ruby.exception_runtime_error(),
                 "DataHasher already finalized",
             )
         })?;
         let r = hasher.finalize(bits).map_err(to_magnus_err)?;
-        let ruby = Ruby::get().expect("called from Ruby");
         let hash = ruby.hash_new();
         hash.aset("iscc", r.iscc)?;
         Ok(hash)
@@ -426,10 +482,11 @@ impl RbInstanceHasher {
     ///
     /// Raises `RuntimeError` if called after `finalize`.
     fn update(&self, data: RString) -> Result<(), Error> {
+        let ruby = Ruby::get().expect("called from Ruby");
         let mut inner = self.inner.borrow_mut();
         let hasher = inner.as_mut().ok_or_else(|| {
             Error::new(
-                magnus::exception::runtime_error(),
+                ruby.exception_runtime_error(),
                 "InstanceHasher already finalized",
             )
         })?;
@@ -445,14 +502,14 @@ impl RbInstanceHasher {
     /// Returns an `RHash` with keys `"iscc"`, `"datahash"`, `"filesize"`.
     /// Raises `RuntimeError` if called more than once.
     fn finalize(&self, bits: u32) -> Result<RHash, Error> {
+        let ruby = Ruby::get().expect("called from Ruby");
         let hasher = self.inner.borrow_mut().take().ok_or_else(|| {
             Error::new(
-                magnus::exception::runtime_error(),
+                ruby.exception_runtime_error(),
                 "InstanceHasher already finalized",
             )
         })?;
         let r = hasher.finalize(bits).map_err(to_magnus_err)?;
-        let ruby = Ruby::get().expect("called from Ruby");
         let hash = ruby.hash_new();
         hash.aset("iscc", r.iscc)?;
         hash.aset("datahash", r.datahash)?;
@@ -477,6 +534,7 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     module.define_module_function("_gen_instance_code_v0", function!(gen_instance_code_v0, 2))?;
     module.define_module_function("_gen_iscc_code_v0", function!(gen_iscc_code_v0, 2))?;
     module.define_module_function("_gen_sum_code_v0", function!(gen_sum_code_v0, 4))?;
+    module.define_module_function("_gen_iscc_id_v1", function!(gen_iscc_id_v1, 3))?;
 
     // Text utility functions
     module.define_module_function("text_clean", function!(text_clean, 1))?;

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: iscc-lib
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Titusz Pan
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-18 00:00:00.000000000 Z
+date: 2026-07-30 00:00:00.000000000 Z
 dependencies: []
 description: High-performance Ruby bindings for ISO 24138:2024 (ISCC). Native Rust
   extension via Magnus for content identification and matching.