Refuse a key-value write too large for its bucket before it is put (issue 774)

mesh-grants' sealed grants and the controller's merge record each met "message size exceeds maximum" (JetStream
10054) only after the put, and a writer that retries looped on a value that can never land; an update over the
limit was even answered as a revision mismatch, which every compare-and-set writer retries.

Quick fix: cap the two values in their modules. Thorough fix, chosen because the kind was met twice and every
module writes through the SDK: the package kvlimit checks a value against its bucket's largest message (read from
its stream and kept) before the put, naming the bucket, the key, the size and the limit, and turns the bus's own
refusal into the same *TooLarge (errors.Is kvlimit.ErrTooLarge), so no writer retries it. The SDK's own writers
use it: process.State (Put, Create, CreateTTL, Update), process.AwaitedBucket, the runtime state of a bundle
(stdio KeptState, against the module state's 256 KiB) and mesh-hand-compose. A value that can outgrow its bucket
is split over keys or kept in the object store with its name in the key.

go/process/buckets.go

@@ -10,6 +10,8 @@ import (
 
 	"github.com/nats-io/nats.go"
 	"github.com/nats-io/nats.go/jetstream"
+
+	"git.novox.be/novox/mesh-sdk/go/kvlimit"
 )
 
 // **A part does not stop for a bucket it can work without** (novox/hq issue 1945, met twice on 2026-10-25: the delivery
@@ -167,7 +169,7 @@ func (b *AwaitedBucket) Put(ctx context.Context, key string, value []byte) (uint
 		kv = b.kv
 		b.mu.Unlock()
 	}
-	return kv.Put(ctx, key, value)
+	return kvlimit.Put(ctx, kv, key, value)
 }
 
 // bind tries one STREAM.INFO of the bucket and, when it is there, binds it; it answers the bucket or nil.
@@ -196,7 +198,7 @@ func (b *AwaitedBucket) bound(kv jetstream.KeyValue, appeared bool) jetstream.Ke
 	written, failed := 0, 0
 	for _, key := range b.order {
 		ctx, cancel := context.WithTimeout(b.ctx, bindWithin)
-		_, err := kv.Put(ctx, key, b.pending[key])
+		_, err := kvlimit.Put(ctx, kv, key, b.pending[key])
 		cancel()
 		if err != nil {
 			failed++

go/process/state.go

@@ -13,6 +13,7 @@ import (
 	"github.com/nats-io/nats.go/jetstream"
 
 	stdio "git.novox.be/novox/mesh-sdk/go"
+	"git.novox.be/novox/mesh-sdk/go/kvlimit"
 )
 
 // stateTimeout bounds a state call (Get, Create, Update) and an Emit (emit.go): a denied publish is
@@ -103,7 +104,7 @@ func (s State) Create(key string, value any) (uint64, error) {
 	if err != nil {
 		return 0, err
 	}
-	rev, err := kv.Create(ctx, key, data)
+	rev, err := kvlimit.Create(ctx, kv, key, data)
 	if errors.Is(err, jetstream.ErrKeyExists) {
 		return 0, fmt.Errorf("%s: %w", key, stdio.ErrChanged)
 	}
@@ -134,7 +135,7 @@ func (s State) CreateTTL(key string, value any, ttl time.Duration) (uint64, erro
 	if err != nil {
 		return 0, err
 	}
-	rev, err := kv.Create(ctx, key, data, jetstream.KeyTTL(ttl))
+	rev, err := kvlimit.Create(ctx, kv, key, data, jetstream.KeyTTL(ttl))
 	if errors.Is(err, jetstream.ErrKeyExists) {
 		return 0, fmt.Errorf("%s: %w", key, stdio.ErrChanged)
 	}
@@ -171,7 +172,7 @@ func (s State) Update(key string, value any, revision uint64) (uint64, error) {
 	if err != nil {
 		return 0, err
 	}
-	rev, err := kv.Update(ctx, key, data, revision)
+	rev, err := kvlimit.Update(ctx, kv, key, data, revision)
 	if errors.Is(err, jetstream.ErrKeyRevisionMismatch) {
 		return 0, fmt.Errorf("%s: %w", key, stdio.ErrChanged)
 	}
@@ -193,7 +194,7 @@ func (s State) Put(key string, value any) (uint64, error) {
 	if err != nil {
 		return 0, err
 	}
-	rev, err := kv.Put(ctx, key, data)
+	rev, err := kvlimit.Put(ctx, kv, key, data)
 	if err != nil {
 		return 0, fmt.Errorf("%s's state %s, key %s: %w", s.Module, s.Name, key, err)
 	}

go/process/state_integration_test.go

@@ -12,6 +12,7 @@ import (
 	"github.com/nats-io/nats.go/jetstream"
 
 	stdio "git.novox.be/novox/mesh-sdk/go"
+	"git.novox.be/novox/mesh-sdk/go/kvlimit"
 )
 
 // 1188/AC1: given a process connection to a test bus granted the bucket mesh-mail_sends, when it creates a
@@ -148,7 +149,8 @@ func TestStateRefusesAnUngrantedBucketNamingIt(t *testing.T) {
 func TestStatePutAndKeysOnAGrantedBucket(t *testing.T) {
 	url, account := grantedSendProcess(t)
 	_, adminJetStream := adminJS(t, url)
-	if _, err := adminJetStream.CreateKeyValue(ctxFor(t), jetstream.KeyValueConfig{Bucket: "mesh-mail_sends"}); err != nil {
+	admins, err := adminJetStream.CreateKeyValue(ctxFor(t), jetstream.KeyValueConfig{Bucket: "mesh-mail_sends", MaxValueSize: 1024})
+	if err != nil {
 		t.Fatalf("the admin could not make the bucket: %v", err)
 	}
 	conn, err := Connect(account)
@@ -158,6 +160,27 @@ func TestStatePutAndKeysOnAGrantedBucket(t *testing.T) {
 	defer conn.Close()
 	s := conn.State("sends")
 
+	// Issue 774 (sweep item 5): a value over the bucket's largest is refused before it is put, naming the bucket, the key,
+	// its size and the limit, as kvlimit.ErrTooLarge, so a writer stops on it; nothing reaches the bucket.
+	big := strings.Repeat("x", 2000)
+	for name, write := range map[string]func() (uint64, error){
+		"put":    func() (uint64, error) { return s.Put("big", big) },
+		"create": func() (uint64, error) { return s.Create("big", big) },
+		"update": func() (uint64, error) { return s.Update("big", big, 1) },
+	} {
+		_, err := write()
+		var tooLarge *kvlimit.TooLarge
+		if !errors.Is(err, kvlimit.ErrTooLarge) || !errors.As(err, &tooLarge) || tooLarge.Limit != 1024 ||
+			tooLarge.Bucket != "mesh-mail_sends" || tooLarge.Key != "big" || tooLarge.Size != 2002 || strings.Contains(err.Error(), "the bus:") {
+			t.Errorf("a %s of 2002 bytes into a bucket of 1024: %v", name, err)
+		}
+	}
+	// The bus's own refusal (JetStream 10054), as a writer that put past the check meets it, is the same refusal.
+	_, err = admins.Put(ctxFor(t), "big", []byte(big))
+	if err == nil || !errors.Is(kvlimit.Refused("mesh-mail_sends", "big", 2000, 1024, err), kvlimit.ErrTooLarge) {
+		t.Errorf("the bus's refusal is not ErrTooLarge: %v", err)
+	}
+
 	if keys, err := s.Keys(); err != nil || len(keys) != 0 {
 		t.Fatalf("Keys of an empty bucket: %v, %v", keys, err)
 	}