Multi Exec Transactions Blueprint

Atomic multi-command execution with optional optimistic locking via WATCH; commands queued and executed sequentially without interruption

Feature	multi-exec-transactions
Category	Workflow
Version	1.0.0
Tags	transactions, atomic-operations, optimistic-locking, rollback, isolation
YAML Source	View on GitHub
JSON API	multi-exec-transactions.json

Actors

ID	Name	Type	Description
client	Client	human	Application executing transactions

Fields

Name	Type	Required	Label	Description
transaction_state	select	No	Transaction State
queued_commands	json	No	Queued Commands
command_results	json	No	Command Results
watched_keys	json	No	Watched Keys
abort_transaction	boolean	No	Abort Transaction

States

State field: transaction_state

Values:

State	Initial	Terminal
idle	Yes
queuing
executing
aborted		Yes

Rules

• general: MULTI marks start of transaction; client queues commands instead of executing, All queued commands execute sequentially without interleaving from other clients, Syntax errors during queueing set EXECABORT flag; EXEC fails entirely, Runtime errors during execution do not abort other commands (partial success possible), WATCH monitors keys; if ANY watched key modified by other client before EXEC, transaction aborts, {“Atomicity guarantee”:”Either all commands execute or none (in case of WATCH violation)”}, No nested MULTI (attempt to MULTI while in transaction returns error), {“Transactions provide isolation”:”Other clients cannot see partial state”}

Outcomes

Multi_start (Priority: 10)

Begin transaction

Given:

• MULTI command
• already_in_transaction (db) eq false

Then:

• transition_state field: transaction_state to: queuing
• set_field target: queued_commands value: ``
• emit_event event: transaction.started

Result: client receives OK; enters queuing mode

Nested_multi_error (Priority: 11) — Error: NESTED_TRANSACTION

Given:

• already_in_transaction (db) eq true

Result: error returned; transaction state unchanged

Queue_command (Priority: 12)

Queue command for transaction

Given:

• transaction_state (db) eq queuing
• command (input) not_in EXEC,DISCARD,WATCH,UNWATCH

Then:

• set_field target: queued_commands — add to queue
• emit_event event: transaction.command_queued

Result: client receives QUEUED; command not executed yet

Queue_syntax_error (Priority: 13) — Error: EXECABORT

Syntax error during queueing

Given:

• syntax_error (computed) eq true

Then:

• set_field target: abort_transaction value: true
• emit_event event: transaction.syntax_error

Result: error returned; EXECABORT flag set; EXEC will fail

Exec_transaction (Priority: 14)

Execute all queued commands atomically

Given:

• EXEC command
• abort_transaction (db) eq false
• watch_violation (db) eq false

Then:

• transition_state field: transaction_state to: executing
• set_field target: command_results — execute all commands in order, store results
• transition_state field: transaction_state to: idle
• emit_event event: transaction.executed

Result: array of results (one per queued command; errors as error objects)

Exec_abort_syntax (Priority: 15) — Error: EXECABORT

EXEC fails due to queueing errors

Given:

• abort_transaction (db) eq true

Then:

• transition_state field: transaction_state to: aborted
• emit_event event: transaction.aborted_syntax

Result: error returned; transaction discarded; client back to idle

Exec_watch_violation (Priority: 16) — Error: WATCH_VIOLATION

EXEC fails due to watched key modification

Given:

• watch_violation (db) eq true

Then:

• transition_state field: transaction_state to: aborted
• emit_event event: transaction.aborted_watch

Result: nil returned; transaction rolled back; watched keys unchanged

Discard_transaction (Priority: 17)

Abort without executing

Given:

• DISCARD command
• transaction_state (db) eq queuing

Then:

• set_field target: queued_commands value: null
• transition_state field: transaction_state to: idle
• emit_event event: transaction.discarded

Result: client receives OK; queued commands discarded

Discard_without_transaction (Priority: 18) — Error: NO_TRANSACTION

Given:

• transaction_state (db) not_in queuing

Result: error returned

Watch_keys (Priority: 20)

Monitor keys for modifications

Given:

• WATCH key [key …]
• transaction_state (db) in idle,queuing

Then:

• set_field target: watched_keys — add to watch list
• emit_event event: transaction.keys_watched

Result: client receives OK; keys now monitored

Unwatch_keys (Priority: 21)

Clear watch list

Given:

• UNWATCH command

Then:

• set_field target: watched_keys value: ``
• emit_event event: transaction.watch_cleared

Result: client receives OK; watch list cleared

Watch_violation_detected (Priority: 22)

Another client modified watched key

Given:

• watched_key_modified (system) eq true
• modifier_client (system) exists

Then:

• set_field target: watch_violation value: true
• emit_event event: transaction.watch_violated

Result: next EXEC returns nil (abort)

Optimistic_lock_read (Priority: 30)

Read value outside transaction

Given:

• GET key (before MULTI)
• WATCH key

Then:

• emit_event event: transaction.optimistic_read

Result: value retrieved; key now watched

Optimistic_lock_compute (Priority: 31)

Compute new value based on read

Given:

• new_value (computed) exists

Then:

• emit_event event: transaction.value_computed

Result: application prepares new value

Optimistic_lock_execute (Priority: 32)

Attempt to update if no concurrent modification

Given:

• MULTI … SET key new_value … EXEC
• key_unchanged (db) eq true

Then:

• emit_event event: transaction.lock_acquired

Result: EXEC succeeds; new value set

Optimistic_lock_retry (Priority: 33)

Retry if concurrent modification detected

Given:

• watch_violation (db) eq true

Then:

• emit_event event: transaction.lock_failed

Result: EXEC returns nil; application retries (GET, compute, MULTI/EXEC)

Command_runtime_error (Priority: 40)

Command fails during execution (e.g., INCR on non-integer)

Given:

• command_executing (system) exists
• runtime_error (system) eq true

Then:

• emit_event event: transaction.command_error

Result: error stored in results array for that command; other commands still execute

Partial_execution (Priority: 41)

Some commands succeed, some fail

Given:

• mixed_results (computed) eq true

Then:

• emit_event event: transaction.partial_success

Result: EXEC returns array with mix of values and error objects

Errors

Code	Status	Message	Retry
NESTED_TRANSACTION	400	MULTI calls can not be nested	No
EXECABORT	400	EXECABORT Transaction discarded because of previous errors	No
NO_TRANSACTION	400	DISCARD without MULTI	No
WATCH_VIOLATION	409	WATCH violation detected	No

Events

Event	Description	Payload
transaction.started
transaction.command_queued
transaction.syntax_error
transaction.executed
transaction.aborted_syntax
transaction.aborted_watch
transaction.discarded
transaction.keys_watched
transaction.watch_cleared
transaction.watch_violated
transaction.optimistic_read
transaction.value_computed
transaction.lock_acquired
transaction.lock_failed
transaction.command_error
transaction.partial_success

Related Blueprints

Feature	Relationship	Reason
string-key-value	optional	Often used to atomically update multiple keys
lua-scripting	optional	Both provide atomicity; scripting more powerful for complex logic

AGI Readiness

Goals

Reliable Multi Exec Transactions

Atomic multi-command execution with optional optimistic locking via WATCH; commands queued and executed sequentially without interruption

Success Metrics:

Metric	Target	Measurement
processing_time	< 5s	Time from request to completion
success_rate	>= 99%	Successful operations divided by total attempts

Constraints:

• performance (negotiable): Must not block dependent workflows

Autonomy

Level: semi_autonomous

Human Checkpoints:

• before transitioning to a terminal state

Escalation Triggers:

• error_rate > 5

Tradeoffs

Prefer	Over	Reason
reliability	speed	workflow steps must complete correctly before proceeding

Safety

Action	Permission	Cooldown	Max Auto
multi_start	autonomous	-	-
nested_multi_error	autonomous	-	-
queue_command	autonomous	-	-
queue_syntax_error	autonomous	-	-
exec_transaction	autonomous	-	-
exec_abort_syntax	autonomous	-	-
exec_watch_violation	autonomous	-	-
discard_transaction	autonomous	-	-
discard_without_transaction	autonomous	-	-
watch_keys	autonomous	-	-
unwatch_keys	autonomous	-	-
watch_violation_detected	autonomous	-	-
optimistic_lock_read	autonomous	-	-
optimistic_lock_compute	autonomous	-	-
optimistic_lock_execute	autonomous	-	-
optimistic_lock_retry	autonomous	-	-
command_runtime_error	autonomous	-	-
partial_execution	autonomous	-	-

Extensions (framework-specific hints)

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