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?
  • scopes(prefix) returns the scope NAMES that start with the prefix, ordered lexicographically (an additive enumeration, for domain stores that name cells hierarchically — "memory:acme", "memory:acme:123")
  • a nested transaction reuses the outer transaction (no SAVEPOINT)
  • a serialization failure on write -> Insika::StoreError (fail-fast)

Backends include Store and override the six 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) 


41
42
43
 
# File 'lib/insika/store.rb', line 41

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

#get(scope, key) ⇒ Object

-> Object | nil (deserialized)

Raises:

  • (NotImplementedError) 


31
32
33
 
# File 'lib/insika/store.rb', line 31

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

#list(scope, prefix = nil) ⇒ Object

-> [String] keys ordered lexicographically

Raises:

  • (NotImplementedError) 


46
47
48
 
# File 'lib/insika/store.rb', line 46

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

#scopes(prefix = nil) ⇒ Object

-> [String] scope names ordered lexicographically, filtered by prefix (start_with?). Added for domain stores with hierarchical scope names.

Raises:

  • (NotImplementedError) 


52
53
54
 
# File 'lib/insika/store.rb', line 52

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

#set(scope, key, value) ⇒ Object

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

Raises:

  • (NotImplementedError) 


36
37
38
 
# File 'lib/insika/store.rb', line 36

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) 


57
58
59
 
# File 'lib/insika/store.rb', line 57

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