Let a bundle write a state key with its own time to live and hear its end, so wakes need no in-process timer (issue 1952)

mesh/state.create and mesh/state.put take ttl_seconds (mesh-sdk 32f5ce3's
CreateTTL/RenewTTL contract); a bucket not declared key-ttl is refused,
naming it; a watch hands an expired key as op "expire". Pins mesh-sdk 32f5ce3.

node-tools/internal/bus/state.go

@@ -37,7 +37,8 @@ type StateEntry struct {
 	Revision uint64          `json:"revision"`
 }
 
-// StateChange is one change a watch delivers: a key put or deleted.
+// StateChange is one change a watch delivers: a key put, deleted, or expired (its own time to live, or the
+// bucket's age, ended; issue 1952).
 type StateChange struct {
 	State    string          `json:"state"`
 	Key      string          `json:"key"`
@@ -199,6 +200,61 @@ func (c *Conn) StatePut(module, name, key string, value json.RawMessage) (uint64
 	return kv.Put(ctx, key, value)
 }
 
+// MinKeyTTL is the shortest time to live a key may be given: the bus counts a key's age in whole seconds (mesh-sdk
+// process.MinTTL).
+const MinKeyTTL = time.Second
+
+// StateCreateTTL writes one key only when it has no value, with its own time to live (novox/hq ADR 0564 clauses 4 and
+// 7, issue 1952; mesh-sdk process.State.CreateTTL): the bus removes it when ttl passes and every watch hears the
+// removal as an expiry, so a bundle's wake needs no timer. A key that has a value is refused as ErrStateChanged. The
+// bucket must take keys with their own time to live (a state declared `key-ttl`); one that does not is refused, naming
+// it, before anything is written.
+func (c *Conn) StateCreateTTL(module, name, key string, value json.RawMessage, ttl time.Duration) (uint64, error) {
+	if ttl < MinKeyTTL {
+		return 0, fmt.Errorf("%s's state %s, key %s: a time to live of %s is shorter than the bus keeps (%s)",
+			module, name, key, ttl, MinKeyTTL)
+	}
+	return c.stateWrite(module, name, key, value, func(ctx context.Context, kv jetstream.KeyValue) (uint64, error) {
+		if err := takesKeyTTL(ctx, kv, module, name); err != nil {
+			return 0, err
+		}
+		return kv.Create(ctx, key, value, jetstream.KeyTTL(ttl))
+	})
+}
+
+// StateRenewTTL writes one key whole with a fresh time to live, whatever it held (mesh-sdk process.State.RenewTTL): a
+// time to live is set only when a key is created, so a live key is deleted first, and its watches hear the delete and
+// then the new value.
+func (c *Conn) StateRenewTTL(module, name, key string, value json.RawMessage, ttl time.Duration) (uint64, error) {
+	rev, err := c.StateCreateTTL(module, name, key, value, ttl)
+	if !errors.Is(err, ErrStateChanged) {
+		return rev, err
+	}
+	if err := c.StateDelete(module, name, key); err != nil {
+		return 0, err
+	}
+	return c.StateCreateTTL(module, name, key, value, ttl)
+}
+
+// takesKeyTTL refuses a bucket that does not allow a time to live per key, or leaves no marker when one ends: there the
+// server would refuse the write, or the key would vanish and no watch would hear it.
+func takesKeyTTL(ctx context.Context, kv jetstream.KeyValue, module, name string) error {
+	status, err := kv.Status(ctx)
+	if err != nil {
+		return err
+	}
+	allows := status.LimitMarkerTTL() > 0
+	if b, ok := status.(*jetstream.KeyValueBucketStatus); ok && b.StreamInfo() != nil {
+		allows = allows && b.StreamInfo().Config.AllowMsgTTL
+	}
+	if !allows {
+		return fmt.Errorf("%s's state %s does not take keys with their own time to live: its bucket %s allows none, or "+
+			"leaves no marker a watch hears when one ends; %s declares the state `key-ttl` for it (novox/hq ADR 0564, "+
+			"issue 1952)", module, name, status.Bucket(), module)
+	}
+	return nil
+}
+
 // StateDelete removes one key, as the module, where the module keeps the state. A key that was not
 // there is not an error: what is asked for is that it is gone.
 func (c *Conn) StateDelete(module, name, key string) error {
@@ -343,6 +399,12 @@ func (c *Conn) StateWatch(module, name, pattern string, deliver func(StateChange
 					continue
 				}
 				change.Op = "delete"
+				if e.Operation() == jetstream.KeyValuePurge {
+					// The marker the server leaves when a key's time to live ends (Nats-Marker-Reason MaxAge,
+					// read by the client as a purge): nothing else purges a module's state, since neither the
+					// runtime nor mesh-sdk's State offers a purge (issue 1952).
+					change.Op = "expire"
+				}
 			}
 			if err := deliver(change); err != nil {
 				c.Logf("[mesh-tools] %s did not take %s %s of %s: %v; its next change, or its next start, reads it again",