fix

Signed-off-by: Hayim.Shaul@ibm.com <hayimsha@fhe03.vpc.cloud9.ibm.com>

Author: Hayim.Shaul@ibm.com

docs/imgs/storage_db.puml

@@ -127,7 +127,7 @@ package "Token Store (TokenDB)" {
         * idx : INT <<PK, NOT NULL, FK>>
         --
         consumer_tx_id : TEXT <<NOT NULL>>
-        created_at : TIMESTAMP <<NOT NULL>>
+        created_at : TIMESTAMPTZ <<NOT NULL>>
     }
 
     entity "TokenSKICleanups" as tkn_ski_cleanups {

docs/services/selector.md

@@ -140,9 +140,11 @@ Two properties of the pass are worth spelling out:
     deleted; the other outputs of the same transaction keep their locks.
 
 The pass is the same statement on every SQL backend, so lock lifetime does not depend on
-whether a deployment runs on SQLite, the in-memory backend, or Postgres. On Postgres a
-single replica per TMS runs it per tick, elected through an advisory lock; SQLite is
-non-distributed and always runs it locally.
+whether a deployment runs on SQLite, the in-memory backend, or Postgres. `created_at` is
+stored as `TIMESTAMPTZ`, so the comparison with the database-side `NOW()` expression is
+always timezone-consistent on Postgres regardless of the session `TimeZone` setting.
+On Postgres a single replica per TMS runs the pass per tick, elected through an advisory
+lock; SQLite is non-distributed and always runs it locally.
 
 ### In-Memory Locker Internals
 

token/services/storage/db/driver/token.go

@@ -339,9 +339,14 @@ type TokenLockStore interface {
 	Lock(ctx context.Context, tokenID *token.ID, consumerTxID transaction.ID, walletID string) error
 	// UnlockByTxID unlocks all tokens locked by the consumer TX
 	UnlockByTxID(ctx context.Context, consumerTxID transaction.ID) error
-	// Cleanup removes the locks such that either:
-	// 1. The transaction that locked that token is valid or invalid;
-	// 2. The lock is too old.
+	// Cleanup removes stale token locks. A lock is stale when either:
+	// 1. The *consuming* transaction (the one trying to spend the token,
+	//    identified by consumer_tx_id) has reached a terminal failure status
+	//    (Deleted or Orphan); or
+	// 2. The lock is older than leaseExpiry (covers consumers that crashed
+	//    before reaching any terminal status).
+	// The producer transaction (the one that created the token, identified by
+	// (tx_id, idx)) is irrelevant to expiry; see #2018.
 	Cleanup(ctx context.Context, leaseExpiry time.Duration) error
 	// AcquireCleanupLeadership attempts to acquire leadership for the
 	// cleanup tick, so only one replica runs Cleanup per tick. Non-distributed

token/services/storage/db/sql/common/tokenlock.go

@@ -95,7 +95,7 @@ func (db *TokenLockStore) GetSchema() string {
 			tx_id TEXT NOT NULL,
 			idx INT NOT NULL,
 			consumer_tx_id TEXT NOT NULL,
-			created_at TIMESTAMP NOT NULL,
+			created_at TIMESTAMPTZ NOT NULL,
 			PRIMARY KEY(tx_id, idx),
 			FOREIGN KEY (tx_id, idx) REFERENCES %s
 		);
@@ -125,7 +125,10 @@ func IsExpiredToken(tokenRequests, tokenLocks common3.Table, leaseExpiry time.Du
 // whether the lock is still live. The condition is correlated rather than a
 // partial-key IN on tx_id, so cleanup removes only the matching (tx_id, idx) rows
 // and leaves the other indices of the same transaction locked. See #2018.
-func IsStaleLock(tokenLocks, tokenRequests common3.Table, leaseExpiry time.Duration) cond.Condition {
+//
+// The argument order matches IsExpiredToken (tokenRequests first, tokenLocks second)
+// so a swapped call is immediately visible and consistent across this file.
+func IsStaleLock(tokenRequests, tokenLocks common3.Table, leaseExpiry time.Duration) cond.Condition {
 	return cond.Or(
 		cond.OlderThan(tokenLocks.Field("created_at"), leaseExpiry),
 		cond.Exists(
@@ -143,12 +146,13 @@ func IsStaleLock(tokenLocks, tokenRequests common3.Table, leaseExpiry time.Durat
 // Cleanup releases the stale token locks: those whose consuming transaction is
 // Deleted or Orphan, and those whose lease is older than leaseExpiry. Only the
 // affected (tx_id, idx) rows are deleted. The same statement is used by every SQL
-// backend, so lock lifetime does not depend on the driver in use.
+// backend. created_at is declared TIMESTAMPTZ so the comparison with the
+// database-side NOW() expression is always timezone-consistent on Postgres.
 func (db *TokenLockStore) Cleanup(ctx context.Context, leaseExpiry time.Duration) error {
 	tokenLocks, tokenRequests := q.Table(db.Table.TokenLocks), q.Table(db.Table.Requests)
 
 	query, args := q.DeleteFrom(db.Table.TokenLocks).
-		Where(IsStaleLock(tokenLocks, tokenRequests, leaseExpiry)).
+		Where(IsStaleLock(tokenRequests, tokenLocks, leaseExpiry)).
 		Format(db.ci)
 
 	db.Logger.Debug(query, args)

token/services/storage/db/sql/postgres/tokenlock.go

@@ -97,6 +97,8 @@ func (db *TokenLockStore) Cleanup(ctx context.Context, leaseExpiry time.Duration
 }
 
 // logStaleLocks logs the token locks that are about to be deleted.
+// NOW() returns timestamptz; created_at is also TIMESTAMPTZ, so both sides of
+// the age comparison are timezone-consistent.
 func (db *TokenLockStore) logStaleLocks(ctx context.Context, leaseExpiry time.Duration) error {
 	if !db.Logger.IsEnabledFor(zapcore.InfoLevel) {
 		return nil

token/services/storage/db/sql/sqlite/tokenlock_test.go

@@ -44,7 +44,7 @@ func TestCleanupSQLShape(t *testing.T) {
 
 	tokenLocks, requests := q.Table("TokenLocks"), q.Table("Requests")
 	query, args := q.DeleteFrom("TokenLocks").
-		Where(common3.IsStaleLock(tokenLocks, requests, 5*time.Second)).
+		Where(common3.IsStaleLock(requests, tokenLocks, 5*time.Second)).
 		Format(NewConditionInterpreter())
 
 	Expect(query).To(ContainSubstring("Requests.tx_id = TokenLocks.consumer_tx_id"))