wippyai
diff --git a/‎Makefile‎
Lines changed: 11 additions & 0 deletions b/‎Makefile‎
Lines changed: 11 additions & 0 deletions
diff --git a/‎api/cluster/raft/config.go‎
Lines changed: 10 additions & 30 deletions b/‎api/cluster/raft/config.go‎
Lines changed: 10 additions & 30 deletions
diff --git a/‎api/service/store/kv/config.go‎
Lines changed: 69 additions & 0 deletions b/‎api/service/store/kv/config.go‎
Lines changed: 69 additions & 0 deletions
diff --git a/‎api/service/store/kv/config_test.go‎
Lines changed: 49 additions & 0 deletions b/‎api/service/store/kv/config_test.go‎
Lines changed: 49 additions & 0 deletions
diff --git a/‎api/store/command.go‎
Lines changed: 81 additions & 5 deletions b/‎api/store/command.go‎
Lines changed: 81 additions & 5 deletions
diff --git a/‎api/store/errors.go‎
Lines changed: 6 additions & 3 deletions b/‎api/store/errors.go‎
Lines changed: 6 additions & 3 deletions
diff --git a/‎api/store/kv/errors.go‎
Lines changed: 15 additions & 0 deletions b/‎api/store/kv/errors.go‎
Lines changed: 15 additions & 0 deletions
@@ -46,6 +46,17 @@ test-network:
 lint:
 	go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.8.0 run --timeout=10m --build-tags=race ./...
 
+# Mutation testing with gremlins. Coverage is scoped to the directory gremlins
+# runs from, so target a package subtree via MUTATE_DIR. workers=1 keeps per-
+# mutant timing free of contention and the generous timeout coefficient stops
+# fast packages (whose cached coverage baseline is tiny) from spuriously timing
+# out while each mutant recompiles — together these make the score deterministic.
+# Example: make mutation MUTATE_DIR=system/topology/namereg/kvbacked
+MUTATE_DIR ?= service/store/kv
+.PHONY: mutation
+mutation:
+	cd $(MUTATE_DIR) && go run github.com/go-gremlins/gremlins/cmd/gremlins@v0.6.0 unleash --workers 1 --timeout-coefficient 30
+
 mock:
 	go tool mockgen -destination tests/mock/identityv1connect/identityv1connect.go github.com/wippyai/module-registry-proto-go/registry/identity/v1/identityv1connect OrganizationServiceClient
 	go tool mockgen -destination tests/mock/modulev1connect/modulev1connect.go github.com/wippyai/module-registry-proto-go/registry/module/v1/modulev1connect ModuleServiceClient,CommitServiceClient,LabelServiceClient,DownloadServiceClient
 
@@ -6,9 +6,10 @@ import "time"
 
 // Config holds configuration for a Raft node.
 //
-// Raft runs with a diskless control plane (in-memory stores): cluster state
-// is ephemeral, restarts rejoin from peer state, persistence-vs-quorum
-// failure modes are removed by construction. There is no data_dir.
+// Raft defaults to a diskless control plane (in-memory stores): cluster state
+// is ephemeral, restarts rejoin from peer state, persistence-vs-quorum failure
+// modes are removed by construction. Setting DataDir opts into fs-durable
+// storage, which a store.kv.raft entry requires.
 //
 // The transport is the wippy internode mesh exclusively: peers are addressed
 // by NodeID over the existing internode connection, so there is no bind
@@ -25,38 +26,17 @@ import "time"
 // see existing peers as raft_status="in" and skip bootstrap; the leader's
 // reconciler adds them via AddVoter.
 type Config struct {
+	DataDir           string        `json:"data_dir,omitempty"`
 	CommitTimeout     time.Duration `json:"commit_timeout"`
 	SnapshotInterval  time.Duration `json:"snapshot_interval"`
 	ElectionTimeout   time.Duration `json:"election_timeout"`
 	HeartbeatTimeout  time.Duration `json:"heartbeat_timeout"`
 	SnapshotThreshold uint64        `json:"snapshot_threshold"`
-	// TrailingLogs caps how many log entries are retained after a snapshot.
-	// hashicorp/raft default is 10240 which keeps a lot of memory under
-	// partition; lower this for memory-constrained nodes. Zero means use
-	// the hashicorp/raft library default.
-	TrailingLogs uint64 `json:"trailing_logs"`
-	// BootstrapExpect is the expected size of the initial quorum. The
-	// gossip-driven bootstrap watcher uses this to decide when to form
-	// the cluster:
-	//   0  -> never self-bootstrap; this node joins an existing cluster
-	//         (waits for the leader's reconciler to AddVoter it).
-	//   1  -> single-node mode; bootstrap immediately with [self].
-	//   N  -> wait for exactly N raft-eligible alive members advertising
-	//         the same BootstrapExpect and raft_status="pre", then all
-	//         N call BootstrapCluster with the deterministically-sorted
-	//         server list. After a full-cluster cold-start they all
-	//         converge on the same configuration at log index 1.
-	BootstrapExpect int `json:"bootstrap_expect,omitempty"`
-	SnapshotRetain  int `json:"snapshot_retain"`
-	MaxPool         int `json:"max_pool"`
-	// MaxAppendEntries caps how many log entries the leader packs into a
-	// single AppendEntries RPC. The hashicorp/raft default is 64 which,
-	// when a follower restarts with an empty log and needs to catch up
-	// hundreds of entries, lets the leader queue large batches in
-	// memory simultaneously. Setting this to 16 throttles the catch-up
-	// throughput so under chaos a returning pod doesn't OOM the leader
-	// while it ships history. Zero means use the library default.
-	MaxAppendEntries int `json:"max_append_entries"`
+	TrailingLogs      uint64        `json:"trailing_logs"`
+	BootstrapExpect   int           `json:"bootstrap_expect,omitempty"`
+	SnapshotRetain    int           `json:"snapshot_retain"`
+	MaxPool           int           `json:"max_pool"`
+	MaxAppendEntries  int           `json:"max_append_entries"`
 }
 
 // InitDefaults fills zero-valued fields with sensible defaults.
 
@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: MPL-2.0
+
+// Package kv provides configuration for the store.kv.* store kinds.
+package kv
+
+import (
+	"regexp"
+
+	apierror "github.com/wippyai/runtime/api/error"
+	"github.com/wippyai/runtime/api/registry"
+	"github.com/wippyai/runtime/api/supervisor"
+)
+
+// Store kind constants.
+const (
+	// KindRaft is a raft-replicated, fs-durable kv store.
+	KindRaft registry.Kind = "store.kv.raft"
+	// KindCRDT is a gossip-CRDT kv store with optional fs durability.
+	KindCRDT registry.Kind = "store.kv.crdt"
+)
+
+// namespacePattern constrains an app namespace so it can never collide with the
+// reserved _sys system namespace (a leading underscore is excluded by the
+// required leading [a-z]). System coordination lives under _sys:* keys.
+var namespacePattern = regexp.MustCompile(`^[a-z][a-z0-9._-]*$`)
+
+// ErrInvalidNamespace is returned for a missing or malformed namespace.
+var ErrInvalidNamespace = apierror.New(apierror.Invalid,
+	"store.kv namespace must match ^[a-z][a-z0-9._-]*$").WithRetryable(apierror.False)
+
+// RaftConfig configures a store.kv.raft entry. Namespace isolates this store's
+// keys within the shared node-wide kv state.
+type RaftConfig struct {
+	Namespace string                     `json:"namespace"`
+	Lifecycle supervisor.LifecycleConfig `json:"lifecycle"`
+}
+
+// Validate checks the configuration.
+func (c *RaftConfig) Validate() error {
+	if !namespacePattern.MatchString(c.Namespace) {
+		return ErrInvalidNamespace
+	}
+	return nil
+}
+
+// InitDefaults fills lifecycle defaults.
+func (c *RaftConfig) InitDefaults() {
+	c.Lifecycle.InitDefaults()
+}
+
+// CRDTConfig configures a store.kv.crdt entry.
+type CRDTConfig struct {
+	Namespace string                     `json:"namespace"`
+	Lifecycle supervisor.LifecycleConfig `json:"lifecycle"`
+	Durable   bool                       `json:"durable"`
+}
+
+// Validate checks the configuration.
+func (c *CRDTConfig) Validate() error {
+	if !namespacePattern.MatchString(c.Namespace) {
+		return ErrInvalidNamespace
+	}
+	return nil
+}
+
+// InitDefaults fills lifecycle defaults.
+func (c *CRDTConfig) InitDefaults() {
+	c.Lifecycle.InitDefaults()
+}
@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: MPL-2.0
+
+package kv
+
+import (
+	"errors"
+	"testing"
+)
+
+// TestConfigValidate_NamespaceReservation pins the prefix-separation guarantee:
+// app namespaces match ^[a-z][a-z0-9._-]*$ so they can never collide with the
+// reserved _sys:* system namespace, and the key separator ':' is excluded so a
+// namespace can never span into another store's keyspace. Both store.kv kinds
+// share the rule; durability is orthogonal to it.
+func TestConfigValidate_NamespaceReservation(t *testing.T) {
+	reserved := []string{"_sys", "_sys:raft", "_sys:registry", "_lock", "_"}
+	malformed := []string{"", "1bad", "BadCase", "a:b", "ns/with/slash", "has space", "UPPER"}
+	valid := []string{"deploy", "sess", "kb", "kb_index", "good.ns", "ok-ns", "a"}
+
+	check := func(t *testing.T, name string, validate func(ns string) error) {
+		t.Helper()
+		for _, ns := range append(append([]string{}, reserved...), malformed...) {
+			if err := validate(ns); !errors.Is(err, ErrInvalidNamespace) {
+				t.Errorf("%s namespace %q: got err=%v, want ErrInvalidNamespace", name, ns, err)
+			}
+		}
+		for _, ns := range valid {
+			if err := validate(ns); err != nil {
+				t.Errorf("%s namespace %q: got err=%v, want nil", name, ns, err)
+			}
+		}
+	}
+
+	t.Run("raft", func(t *testing.T) {
+		check(t, "raft", func(ns string) error {
+			c := RaftConfig{Namespace: ns}
+			return c.Validate()
+		})
+	})
+
+	t.Run("crdt is identical and orthogonal to durability", func(t *testing.T) {
+		for _, durable := range []bool{false, true} {
+			check(t, "crdt", func(ns string) error {
+				c := CRDTConfig{Namespace: ns, Durable: durable}
+				return c.Validate()
+			})
+		}
+	})
+}
@@ -12,17 +12,20 @@ import (
 
 func init() {
 	dispatcher.MustRegisterCommands("store",
-		Get, Set, Delete, Has,
+		Get, Set, Delete, Has, EntryCommand, ListCommand, PutCommand,
 	)
 }
 
 // Command IDs for store operations.
 // Range 120-129 is reserved for key-value store commands.
 const (
-	Get    dispatcher.CommandID = 120 // Get value by key
-	Set    dispatcher.CommandID = 121 // Set value with key
-	Delete dispatcher.CommandID = 122 // Delete key
-	Has    dispatcher.CommandID = 123 // Check if key exists
+	Get          dispatcher.CommandID = 120 // Get value by key
+	Set          dispatcher.CommandID = 121 // Set value with key
+	Delete       dispatcher.CommandID = 122 // Delete key
+	Has          dispatcher.CommandID = 123 // Check if key exists
+	EntryCommand dispatcher.CommandID = 124 // Get value with metadata
+	ListCommand  dispatcher.CommandID = 125 // List keys deterministically
+	PutCommand   dispatcher.CommandID = 126 // Rich put with conditions
 )
 
 // GetCmd retrieves a value from the store.
@@ -93,6 +96,61 @@ func (c *HasCmd) Release() {
 	hasCmdPool.Put(c)
 }
 
+// EntryCmd retrieves a value with store metadata.
+type EntryCmd struct {
+	Store Store
+	Key   registry.ID
+}
+
+var entryCmdPool = sync.Pool{New: func() any { return &EntryCmd{} }}
+
+// AcquireEntryCmd returns a pooled EntryCmd.
+func AcquireEntryCmd() *EntryCmd                { return entryCmdPool.Get().(*EntryCmd) }
+func (c *EntryCmd) CmdID() dispatcher.CommandID { return EntryCommand }
+func (c *EntryCmd) Release() {
+	c.Store = nil
+	c.Key = registry.ID{}
+	entryCmdPool.Put(c)
+}
+
+// ListCmd lists store entries.
+type ListCmd struct {
+	Store Store
+	Opts  ListOptions
+}
+
+var listCmdPool = sync.Pool{New: func() any { return &ListCmd{} }}
+
+// AcquireListCmd returns a pooled ListCmd.
+func AcquireListCmd() *ListCmd                 { return listCmdPool.Get().(*ListCmd) }
+func (c *ListCmd) CmdID() dispatcher.CommandID { return ListCommand }
+func (c *ListCmd) Release() {
+	c.Store = nil
+	c.Opts = ListOptions{}
+	listCmdPool.Put(c)
+}
+
+// PutCmd writes a value with optional preconditions.
+type PutCmd struct {
+	Store Store
+	Value payload.Payload
+	Key   registry.ID
+	Opts  PutOptions
+}
+
+var putCmdPool = sync.Pool{New: func() any { return &PutCmd{} }}
+
+// AcquirePutCmd returns a pooled PutCmd.
+func AcquirePutCmd() *PutCmd                  { return putCmdPool.Get().(*PutCmd) }
+func (c *PutCmd) CmdID() dispatcher.CommandID { return PutCommand }
+func (c *PutCmd) Release() {
+	c.Store = nil
+	c.Key = registry.ID{}
+	c.Value = nil
+	c.Opts = PutOptions{}
+	putCmdPool.Put(c)
+}
+
 // GetResponse contains the result of a get operation.
 type GetResponse struct {
 	Value payload.Payload
@@ -115,3 +173,21 @@ type HasResponse struct {
 	Error  error
 	Exists bool
 }
+
+// EntryResponse contains an entry plus metadata.
+type EntryResponse struct {
+	Error error
+	Entry VersionedEntry
+}
+
+// ListResponse contains a deterministic list page.
+type ListResponse struct {
+	Error error
+	Page  Page
+}
+
+// PutResponse contains the stored entry.
+type PutResponse struct {
+	Error error
+	Entry VersionedEntry
+}
@@ -8,7 +8,10 @@ import (
 
 // Sentinel errors.
 var (
-	ErrKeyNotFound = apierror.New(apierror.NotFound, "key not found").WithRetryable(apierror.False)
-	ErrKeyExists   = apierror.New(apierror.AlreadyExists, "key already exists").WithRetryable(apierror.False)
-	ErrInvalidKey  = apierror.New(apierror.Invalid, "invalid key format").WithRetryable(apierror.False)
+	ErrKeyNotFound     = apierror.New(apierror.NotFound, "key not found").WithRetryable(apierror.False)
+	ErrKeyExists       = apierror.New(apierror.AlreadyExists, "key already exists").WithRetryable(apierror.False)
+	ErrInvalidKey      = apierror.New(apierror.Invalid, "invalid key format").WithRetryable(apierror.False)
+	ErrInvalidOptions  = apierror.New(apierror.Invalid, "invalid store options").WithRetryable(apierror.False)
+	ErrUnsupported     = apierror.New(apierror.Invalid, "operation not supported by this store").WithRetryable(apierror.False)
+	ErrVersionMismatch = apierror.New(apierror.Conflict, "version mismatch").WithRetryable(apierror.True)
 )
@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: MPL-2.0
+
+package kv
+
+import apierror "github.com/wippyai/runtime/api/error"
+
+// Engine sentinel errors.
+var (
+	ErrKeyNotFound     = apierror.New(apierror.NotFound, "key not found").WithRetryable(apierror.False)
+	ErrLeaseNotFound   = apierror.New(apierror.NotFound, "lease not found").WithRetryable(apierror.False)
+	ErrLeaseExpired    = apierror.New(apierror.Invalid, "lease has expired").WithRetryable(apierror.False)
+	ErrVersionMismatch = apierror.New(apierror.Invalid, "version mismatch").WithRetryable(apierror.True)
+	ErrKVClosed        = apierror.New(apierror.Unavailable, "kv is closed").WithRetryable(apierror.False)
+	ErrUnsupported     = apierror.New(apierror.Invalid, "operation not supported by this backend").WithRetryable(apierror.False)
+)