lutaml-store 0.3.2 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3666640ef12a937789e1fa2357edbb7bb882468a78fac8053e8bcc0efbe94ccd
-  data.tar.gz: da2a66ff3067ead5082ff16a6abea51232e49359a63b84e4cde45a3e42c768ac
+  metadata.gz: b35bad6d5f81534647fb355041ff434f9155e4488121d0870ef40611c1b9dc93
+  data.tar.gz: 71bca0ca15d5134199bad07710cb2bad8b35c3369abc5426a22bfa299352ba4a
 SHA512:
-  metadata.gz: 3d8eba2c1775fc8ac1fd170c4134be61046954212319ba63e5d6ca8ffeca845a5e3a808e49fded3668f6dba387d7f75b326a6b7821e17375f658a4ad76c92b75
-  data.tar.gz: 75f6f23cbfd0f30cc58a7d21f45906878d260f07bf4b2201b84ca75493233d79406c71df1692353a7e263df962f5a34e498007ecc11c7a0ed46c2ffa89db4c97
+  metadata.gz: eb4a0da9eb8a5dc529d8dbac816b8e1c98cc0da1826b7c9be5e04ceb9ae92b7e1fb3bbac65eca28f7c7a90025adf7391918beb5270e5b081c92baee31ffb69c5
+  data.tar.gz: af1af6380f9cd19f0ae14f1d7fc7987ae15cc47f26535338d919fa8cac2f83ceef84a4084a7f80bf626617182da65318d0207c6086274df078b388dbb4811b65

data/docs/src/pages/stores.md

@@ -76,6 +76,28 @@ cache.fetch("key") { expensive_call }     # block runs only on miss
 
 Entries past their TTL are evicted lazily on access; when `max_size` is exceeded the least-recently-used entries are evicted first.
 
+### TTL guarantees (pinned)
+
+The TTL semantics are pinned by specs and safe to build expiry policy on:
+
+- **Persistence** — entries serialize `created_at` as ISO-8601 with
+  microsecond precision, so a FileSystem (or SQLite) cache reopened in a new
+  process keeps every entry's original clock; expiry survives restarts.
+  The memory adapter keeps no state across processes by nature.
+- **Clock** — wall clock, not monotonic. This is the deliberate trade:
+  wall-clock timestamps survive restarts, but a system clock jump changes
+  apparent freshness (a backward jump un-expires nothing an entry's absolute
+  `created_at + ttl` already expired). Consumers needing jump-immunity
+  re-derive freshness from the source.
+- **Expired reads** — `get` on an expired entry returns `nil` **and deletes
+  the entry**: the key disappears from `keys`/`size`/`exists?`.
+- **Sweep** — expiry is lazy-on-read plus an opportunistic
+  `cleanup_expired` (interval `cleanup_interval`, default 300 s) invoked
+  inside mutating reads. There is **no background reaper**; a consumer like
+  the relaton shard cache needs none.
+- **TTL values** — `ttl: nil` (and no `default_ttl`) never expires;
+  `ttl: 0` is immediately expired.
+
 ## PackageStore — multi-model packages
 
 ```ruby

data/lib/lutaml/store/cache_store.rb

@@ -36,10 +36,12 @@ module Lutaml
 
         def to_h
           {
+            # sub-second precision: a second-truncated created_at shortens
+            # every restored TTL by up to a second (matters at small TTLs)
             value: @value,
-            created_at: @created_at.iso8601,
+            created_at: @created_at.iso8601(6),
             ttl: @ttl,
-            expires_at: expires_at&.iso8601,
+            expires_at: expires_at&.iso8601(6),
             metadata: @metadata
           }
         end

data/lib/lutaml/store/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Store
-    VERSION = "0.3.2"
+    VERSION = "0.3.3"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-store
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.3.3
 platform: ruby
 authors:
 - Ronald Tse
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-29 00:00:00.000000000 Z
+date: 2026-11-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lutaml-model
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.8.15
+        version: 0.8.156
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.8.15
+        version: 0.8.156
 - !ruby/object:Gem::Dependency
   name: rubyzip
   requirement: !ruby/object:Gem::Requirement