Module: Insika::Store

Included in:
Insika::Stores::Memory, Insika::Stores::SQLite
Defined in:
lib/insika/store.rb

Overview

Minimal persistence contract. Namespace-scoped KV, transactional when the backend supports it. Every implementation passes the SAME contract suite (lib/insika/testing/store_contract.rb — requirable from outside the repo, Values must be JSON-serializable.

scope: String — separates domains/tenants (e.g. "sessions", "tasks:tenant_x") key: Hierarchical String (e.g. "task:123", "checkpoint:123:turn:4")

Contract rules (verified by the suite):

  • get on a nonexistent key -> nil (never an exception)
  • set overwrites silently (last-write-wins)
  • round-trip preserves JSON types; Symbols become Strings (the domain normalizes at the boundary)
  • list(scope) returns only keys of the scope, ordered lexicographically; prefix filters by start_with?
  • a nested transaction reuses the outer transaction (no SAVEPOINT)
  • a serialization failure on write -> Insika::StoreError (fail-fast)

Backends include Store and override the five methods; any forgotten method raises NotImplementedError (fail-fast, better than a distant NoMethodError).

Instance Method Summary collapse

Instance Method Details

#delete(scope, key) ⇒ Object

-> true | false (did it exist?)

Raises:

  • (NotImplementedError) 


38
39
40
 
# File 'lib/insika/store.rb', line 38

def delete(scope, key)
  raise NotImplementedError, "#{self.class}#delete"
end

#get(scope, key) ⇒ Object

-> Object | nil (deserialized)

Raises:

  • (NotImplementedError) 


28
29
30
 
# File 'lib/insika/store.rb', line 28

def get(scope, key)
  raise NotImplementedError, "#{self.class}#get"
end

#list(scope, prefix = nil) ⇒ Object

-> [String] keys ordered lexicographically

Raises:

  • (NotImplementedError) 


43
44
45
 
# File 'lib/insika/store.rb', line 43

def list(scope, prefix = nil)
  raise NotImplementedError, "#{self.class}#list"
end

#set(scope, key, value) ⇒ Object

-> value (the SAME object passed in, not the round-trip)

Raises:

  • (NotImplementedError) 


33
34
35
 
# File 'lib/insika/store.rb', line 33

def set(scope, key, value)
  raise NotImplementedError, "#{self.class}#set"
end

#transaction(&blk) ⇒ Object

-> the block's result; atomic if the backend supports it

Raises:

  • (NotImplementedError) 


48
49
50
 
# File 'lib/insika/store.rb', line 48

def transaction(&blk)
  raise NotImplementedError, "#{self.class}#transaction"
end