Sorted Set And Hash Operations Blueprint

Sorted collections with ranking and scoring; nested key-value maps with field-level operations and optional TTL per field


Feature	`sorted-set-and-hash-operations`
Category	Data
Version	1.0.0
Tags	sorted-sets, hashes, nested-kv, scoring, field-expiration, ranking
YAML Source	View on GitHub
JSON API	sorted-set-and-hash-operations.json

Actors

ID	Name	Type	Description
`client`	Client	human	Application requesting sorted set or hash operations

Fields

Name	Type	Required	Label
`key`	text	Yes	Key
`members`	json	No	Members
`fields`	json	No	Fields
`score`	number	No	Score
`field_ttl_ms`	number	No	Field Ttl Ms

States

State field: presence

Values:

State	Initial	Terminal
`absent`	Yes
`present`
`empty`		Yes

Rules

general: Sorted set members are unique; adding existing member updates score, Scores can be equal; ties broken by lexicographic member order, Scores can be negative, infinity (-inf), or +inf, Range queries support inclusive and exclusive boundaries, Rank is 0-based (0 = lowest score, -1 = highest score in reverse), Lex ranges require all members to have identical scores, Hash fields are unique strings; updating field overwrites value, Hash supports per-field TTL (field expires independently), Numeric field operations (HINCRBY) increment field values, Fields are unordered unless scanning with HSCAN

Outcomes

Zadd_members (Priority: 10)

Add or update members with scores

Given:

command (input) eq ZADD
nx_xx_compat (input) not_in NX+XX

Then:

set_field target: members — add new members or update scores
emit_event event: zset.added

Result: new member count or changed count (with CH flag); client receives count

Zadd_incr (Priority: 11)

Increment member score

Given:

incr_flag (input) eq INCR

Then:

set_field target: members — increment score (create if missing)
emit_event event: zset.scored

Result: new score returned (as string)

Zadd_conditional (Priority: 12)

Add only if condition met (NX, XX, GT, LT)

Given:

condition (input) in NX,XX,GT,LT
condition_met (computed) eq true

Then:

set_field target: members
emit_event event: zset.conditional_add

Result: member added/updated if condition met; client receives count

Zrem_members (Priority: 13)

Remove members by name

Given:

ZREM key member [member …]

Then:

set_field target: members — remove specified members
emit_event event: zset.removed

Result: client receives count of removed members

Zrange_by_rank (Priority: 20)

Get members by index range

Given:

ZRANGE key start stop [WITHSCORES]
range_type (input) eq rank

Then:

emit_event event: zset.range_rank

Result: array of members (with scores if WITHSCORES); empty if out-of-range

Zrange_by_score (Priority: 21)

Get members by score range

Given:

ZRANGE key min max BYSCORE [WITHSCORES] [LIMIT offset count]
min_score (input) exists
max_score (input) exists

Then:

emit_event event: zset.range_score

Result: array of members in score range [min, max] (exclusive with ‘(‘ prefix; handles -inf/+inf)

Zrange_by_lex (Priority: 22)

Get members by lexicographic range (requires equal scores)

Given:

ZRANGE key min max BYLEX [LIMIT offset count]
all_equal_scores (db) eq true

Then:

emit_event event: zset.range_lex

Result: array of members in lex range [min, max] (exclusive with ‘(‘ prefix; handles -/+)

Zrank_member (Priority: 23)

Get member rank by position

Given:

ZRANK key member [WITHSCORE]

Then:

emit_event event: zset.rank

Result: 0-based rank (or nil if member absent); score included if WITHSCORE

Zscore_member (Priority: 24)

Get member score

Given:

ZSCORE key member

Then:

emit_event event: zset.score_read

Result: score as string (or nil if member absent)

Zinter_sets (Priority: 30)

Get intersection of sorted sets

Given:

ZINTER numkeys key [key …] [WEIGHTS weight …] [AGGREGATE SUM MIN MAX]
weights (input) exists
aggregate (input) exists

Then:

emit_event event: zset.inter

Result: array of members in all sets (scores combined per AGGREGATE)

Zunion_sets (Priority: 31)

Get union of sorted sets

Given:

ZUNION numkeys key [key …] [WEIGHTS weight …] [AGGREGATE SUM MIN MAX]

Then:

emit_event event: zset.union

Result: array of members in any set (scores combined per AGGREGATE)

Hset_fields (Priority: 40)

Set one or more field-value pairs

Given:

command (input) in HSET,HMSET
field_value_pairs (input) exists

Then:

set_field target: fields — set or update fields
emit_event event: hash.set

Result: count of new fields added (HSET) or OK (HMSET)

Hget_field (Priority: 41)

Get single field value

Given:

HGET key field

Then:

emit_event event: hash.field_read

Result: field value (or nil if field absent or expired)

Hmget_fields (Priority: 42)

Get multiple field values

Given:

HMGET key field [field …]

Then:

emit_event event: hash.multi_read

Result: array with value for each field (nil for missing/expired fields)

Hgetall_fields (Priority: 43)

Get all field-value pairs

Given:

HGETALL key

Then:

emit_event event: hash.all_read

Result: flattened array [field1, value1, field2, value2, …] (excludes expired fields)

Hkeys_fields (Priority: 44)

Get all field names

Given:

HKEYS key

Then:

emit_event event: hash.keys_read

Result: array of all field names (excludes expired)

Hvals_values (Priority: 45)

Get all field values

Given:

HVALS key

Then:

emit_event event: hash.vals_read

Result: array of all values (excludes expired fields)

Hdel_fields (Priority: 46)

Delete fields

Given:

HDEL key field [field …]

Then:

set_field target: fields — remove specified fields
emit_event event: hash.deleted

Result: count of deleted fields; hash deleted if empty

Hincrby_field (Priority: 47)

Increment field value by integer

Given:

HINCRBY key field increment
value (db) matches ^-?[0-9]+$

Then:

set_field target: fields — increment field (create if absent)
emit_event event: hash.incr

Result: new field value after increment

Hincrbyfloat_field (Priority: 48)

Increment field value by float

Given:

HINCRBYFLOAT key field increment

Then:

set_field target: fields — increment field by float
emit_event event: hash.incrbyfloat

Result: new field value as decimal string

Hexists_field (Priority: 49)

Check if field exists

Given:

HEXISTS key field

Then:

emit_event event: hash.exists_check

Result: 1 if field exists and not expired, 0 otherwise

Hlen_hash (Priority: 50)

Get hash field count

Given:

HLEN key

Then:

emit_event event: hash.count

Result: number of fields (after lazy-expiring expired fields)

Hexpire_field (Priority: 60)

Set field expiration time (seconds)

Given:

HEXPIRE key [NX XX GT LT] seconds FIELDS count field [field …]
condition (input) exists

Then:

set_field target: field_ttl_ms — set absolute expiration timestamp
emit_event event: hash.expire_set

Result: array with count of affected fields per condition

Hpexpire_field (Priority: 61)

Set field expiration time (milliseconds)

Given:

HPEXPIRE key [condition] milliseconds FIELDS count field [field …]

Then:

set_field target: field_ttl_ms — set absolute expiration (milliseconds precision)
emit_event event: hash.pexpire_set

Result: array with affected field counts

Hpersist_field (Priority: 62)

Remove field expiration (make permanent)

Given:

HPERSIST key FIELDS count field [field …]

Then:

set_field target: field_ttl_ms value: null — remove TTL
emit_event event: hash.persist

Result: array with count of fields that had TTL removed

Httl_field (Priority: 63)

Get field TTL (seconds)

Given:

HTTL key field [field …]

Then:

emit_event event: hash.ttl_read

Result: array of TTLs in seconds (-1=no-ttl, -2=field-absent)

Hscan_fields (Priority: 70)

Iterate fields with cursor

Given:

HSCAN key cursor [MATCH pattern] [COUNT count]

Then:

emit_event event: hash.scan

Result: array [new_cursor, [field1, value1, field2, value2, …]]

Errors

Code	Status	Message	Retry
`NOT_AN_INTEGER`	400	Hash value is not an integer	No
`WRONG_TYPE`	400	Operation against a key holding the wrong kind of value	No
`SYNTAX_ERROR`	400	Syntax error in score or condition	No

Events

Event	Description	Payload
`zset.added`
`zset.conditional_add`
`zset.removed`
`zset.range_rank`
`zset.range_score`
`zset.range_lex`
`zset.rank`
`zset.score_read`
`zset.inter`
`zset.union`
`hash.set`
`hash.field_read`
`hash.multi_read`
`hash.all_read`
`hash.keys_read`
`hash.vals_read`
`hash.deleted`
`hash.incr`
`hash.incrbyfloat`
`hash.exists_check`
`hash.count`
`hash.expire_set`
`hash.pexpire_set`
`hash.persist`
`hash.ttl_read`
`hash.scan`

Feature	Relationship	Reason
string-key-value	optional	Hash fields and sorted set members are strings
key-expiration	required	Hashes support per-field TTL

AGI Readiness

Goals

Reliable Sorted Set And Hash Operations

Sorted collections with ranking and scoring; nested key-value maps with field-level operations and optional TTL per field

Success Metrics:

Metric	Target	Measurement
data_accuracy	100%	Records matching source of truth
duplicate_rate	0%	Duplicate records detected post-creation

Constraints:

performance (non-negotiable): Data consistency must be maintained across concurrent operations

Autonomy

Level: supervised

Human Checkpoints:

before transitioning to a terminal state

Escalation Triggers:

error_rate > 5

Tradeoffs

Prefer	Over	Reason
data_integrity	performance	data consistency must be maintained across all operations

Coordination

Protocol: orchestrated

Consumes:

Capability	From	Fallback
`key_expiration`	key-expiration	degrade

Safety

Action	Permission	Cooldown	Max Auto
zadd_members	`autonomous`	-	-
zadd_incr	`autonomous`	-	-
zadd_conditional	`autonomous`	-	-
zrem_members	`autonomous`	-	-
zrange_by_rank	`autonomous`	-	-
zrange_by_score	`autonomous`	-	-
zrange_by_lex	`autonomous`	-	-
zrank_member	`autonomous`	-	-
zscore_member	`autonomous`	-	-
zinter_sets	`autonomous`	-	-
zunion_sets	`autonomous`	-	-
hset_fields	`autonomous`	-	-
hget_field	`autonomous`	-	-
hmget_fields	`autonomous`	-	-
hgetall_fields	`autonomous`	-	-
hkeys_fields	`autonomous`	-	-
hvals_values	`autonomous`	-	-
hdel_fields	`autonomous`	-	-
hincrby_field	`autonomous`	-	-
hincrbyfloat_field	`autonomous`	-	-
hexists_field	`autonomous`	-	-
hlen_hash	`autonomous`	-	-
hexpire_field	`autonomous`	-	-
hpexpire_field	`autonomous`	-	-
hpersist_field	`autonomous`	-	-
httl_field	`autonomous`	-	-
hscan_fields	`autonomous`	-	-

Extensions (framework-specific hints)

```yaml source: repo: https://github.com/redis/redis project: Redis tech_stack: C files_traced: 2 entry_points: - src/t_zset.c - src/t_hash.c ```

Sorted Set And Hash Operations Blueprint

Actors

Fields

States

Rules

Outcomes

Zadd_members (Priority: 10)

Zadd_incr (Priority: 11)

Zadd_conditional (Priority: 12)

Zrem_members (Priority: 13)

Zrange_by_rank (Priority: 20)

Zrange_by_score (Priority: 21)

Zrange_by_lex (Priority: 22)

Zrank_member (Priority: 23)

Zscore_member (Priority: 24)

Zinter_sets (Priority: 30)

Zunion_sets (Priority: 31)

Hset_fields (Priority: 40)

Hget_field (Priority: 41)

Hmget_fields (Priority: 42)

Hgetall_fields (Priority: 43)

Hkeys_fields (Priority: 44)

Hvals_values (Priority: 45)

Hdel_fields (Priority: 46)

Hincrby_field (Priority: 47)

Hincrbyfloat_field (Priority: 48)

Hexists_field (Priority: 49)

Hlen_hash (Priority: 50)

Hexpire_field (Priority: 60)

Hpexpire_field (Priority: 61)

Hpersist_field (Priority: 62)

Httl_field (Priority: 63)

Hscan_fields (Priority: 70)

Errors

Events

Related Blueprints

AGI Readiness

Goals

Reliable Sorted Set And Hash Operations

Autonomy

Tradeoffs

Coordination

Safety