Pub Sub Messaging Blueprint

Real-time fire-and-forget message broadcasting with direct channel subscriptions and pattern-based subscriptions; sharded variant for cluster deployments


Feature	`pub-sub-messaging`
Category	Integration
Version	1.0.0
Tags	pub-sub, real-time-messaging, broadcast, pattern-matching, no-persistence
YAML Source	View on GitHub
JSON API	pub-sub-messaging.json

Actors

ID	Name	Type	Description
`publisher`	Publisher	system	Sends messages to channels
`subscriber`	Subscriber	system	Receives messages from subscribed channels
`global_pubsub`	Global Pub/Sub	system	Global message broker (non-sharded)
`sharded_pubsub`	Sharded Pub/Sub	system	Per-shard message broker (cluster mode)

Fields

Name	Type	Required	Label
`channel_name`	text	Yes	Channel Name
`pattern`	text	No	Pattern
`message`	text	No	Message
`subscriber_count`	number	No	Subscriber Count
`pattern_subscriber_count`	number	No	Pattern Subscriber Count

States

State field: subscriber_state

Values:

State	Initial	Terminal
`not_subscribed`	Yes
`subscribed`
`connected`

Rules

general: Messages are fire-and-forget (no persistence, no replay), Subscribers must be connected when message published to receive it, Offline subscribers miss all messages published while disconnected, No message ordering guarantee across multiple subscribers, Subscriber enters “subscription mode” and can only use subscription commands, Pattern subscriptions use glob matching (* = any, ? = single char, [abc] = set), Sharded pub/sub messages routed by slot (like hash sharding), Sharded pub/sub only reaches nodes owning the shard, Subscriber can have multiple channel and pattern subscriptions, Unsubscribe with empty list = unsubscribe from all

Outcomes

Publish_message (Priority: 10)

Send message to channel

Given:

PUBLISH channel message
channel (input) exists
message (input) exists

Then:

emit_event event: pubsub.message_published

Result: client receives count of subscribers that received the message

Publish_no_subscribers (Priority: 11)

Given:

subscriber_count (db) eq 0
pattern_subscriber_count (db) eq 0

Then:

emit_event event: pubsub.published_to_empty

Result: message discarded; client receives 0

Sharded_publish (Priority: 12)

Publish to shard channel (cluster mode)

Given:

SPUBLISH shard_channel message
shard_owned_by_this_node (system) eq true

Then:

emit_event event: pubsub.sharded_published

Result: count of subscribers on this shard that received message

Subscribe_to_channels (Priority: 20)

Subscribe to one or more channels

Given:

SUBSCRIBE channel [channel …]
channels (input) exists

Then:

transition_state field: subscriber_state to: subscribed
emit_event event: pubsub.subscribed

Result: client enters subscription mode; receives subscription confirmation; starts receiving messages

Subscribe_pattern (Priority: 21)

Subscribe to channels matching pattern

Given:

PSUBSCRIBE pattern [pattern …]
patterns (input) exists

Then:

transition_state field: subscriber_state to: subscribed
emit_event event: pubsub.pattern_subscribed

Result: client enters subscription mode; receives pattern subscription confirmation

Receive_message (Priority: 22)

Receive message from subscribed channel

Given:

message_published (system) exists
subscriber_state (db) eq subscribed

Then:

emit_event event: pubsub.message_received

Result: message delivered to subscriber in format [type, channel/pattern, message]

Receive_pattern_match (Priority: 23)

Receive message via pattern subscription

Given:

channel_matches_pattern (system) eq true
pattern_subscribed (db) eq true

Then:

emit_event event: pubsub.pattern_message_received

Result: message delivered in format [ptype, pattern, channel, message]

Sharded_subscribe (Priority: 24)

Subscribe to shard channel

Given:

SSUBSCRIBE shard_channel [shard_channel …]

Then:

transition_state field: subscriber_state to: subscribed
emit_event event: pubsub.sharded_subscribed

Result: client enters subscription mode; receives shard channel confirmations

Unsubscribe_from_channels (Priority: 30)

Stop subscribing to channels

Given:

UNSUBSCRIBE [channel …]
channels (input) exists

Then:

emit_event event: pubsub.unsubscribed

Result: receives unsubscription confirmations; client exits subscription mode if no subscriptions remain

Unsubscribe_from_patterns (Priority: 31)

Stop subscribing to patterns

Given:

PUNSUBSCRIBE [pattern …]
patterns (input) exists

Then:

emit_event event: pubsub.pattern_unsubscribed

Result: receives unsubscription confirmations; exits subscription mode if no subscriptions remain

Exit_subscription_mode (Priority: 32)

Given:

remaining_subscriptions (computed) eq 0

Then:

transition_state field: subscriber_state to: not_subscribed
emit_event event: pubsub.mode_exited

Result: subscriber back in normal mode; can execute non-pub/sub commands

Sharded_unsubscribe (Priority: 33)

Stop subscribing to shard channels

Given:

SUNSUBSCRIBE [shard_channel …]

Then:

emit_event event: pubsub.sharded_unsubscribed

Result: unsubscription confirmations

Command_in_subscription_mode (Priority: 40) — Error: `SUBSCRIPTION_MODE`

Attempt non-pub/sub command while subscribed

Given:

subscriber_state (db) eq subscribed
command (input) not_in SUBSCRIBE,PSUBSCRIBE,UNSUBSCRIBE,PUNSUBSCRIBE,PING,QUIT,HELLO,RESET

Then:

emit_event event: pubsub.invalid_command

Result: error returned; command not executed; subscription mode unchanged

Ping_while_subscribed (Priority: 41)

PING allowed in subscription mode

Given:

subscriber_state (db) eq subscribed
PING [message]

Then:

emit_event event: pubsub.pong

Result: [pong, message-or-nil]

Pubsub_channels (Priority: 50)

List active channels

Given:

PUBSUB CHANNELS [pattern]
pattern (input) exists

Then:

emit_event event: pubsub.channels_listed

Result: array of active channel names (with subscribers)

Pubsub_numsub (Priority: 51)

Get subscriber count per channel

Given:

PUBSUB NUMSUB channel [channel …]

Then:

emit_event event: pubsub.numsub_queried

Result: flattened array [channel1, count1, channel2, count2, …]

Pubsub_numpat (Priority: 52)

Get total pattern subscription count

Given:

PUBSUB NUMPAT

Then:

emit_event event: pubsub.numpat_queried

Result: total count of pattern subscriptions across all clients

Errors

Code	Status	Message	Retry
`SUBSCRIPTION_MODE`	400	Only (P)SUBSCRIBE / (P)UNSUBSCRIBE / PING / QUIT allowed in this context	No
`WRONG_TYPE`	400	Operation against a key holding the wrong kind of value	No

Events

Event	Description	Payload
`pubsub.message_published`
`pubsub.published_to_empty`
`pubsub.sharded_published`
`pubsub.subscribed`
`pubsub.pattern_subscribed`
`pubsub.message_received`
`pubsub.pattern_message_received`
`pubsub.sharded_subscribed`
`pubsub.unsubscribed`
`pubsub.pattern_unsubscribed`
`pubsub.mode_exited`
`pubsub.sharded_unsubscribed`
`pubsub.invalid_command`
`pubsub.pong`
`pubsub.channels_listed`
`pubsub.numsub_queried`
`pubsub.numpat_queried`

Feature	Relationship	Reason
stream-event-log	optional	Both deliver messages; Pub/Sub is ephemeral, Streams are persistent
message-queue	optional	Pub/Sub is broadcast (no ack), message queues have ack and guaranteed delivery

AGI Readiness

Goals

Reliable Pub Sub Messaging

Real-time fire-and-forget message broadcasting with direct channel subscriptions and pattern-based subscriptions; sharded variant for cluster deployments

Success Metrics:

Metric	Target	Measurement
success_rate	>= 99.5%	Successful operations divided by total attempts
error_recovery_rate	>= 95%	Errors that auto-recover without manual intervention

Constraints:

availability (non-negotiable): Must degrade gracefully when dependencies are unavailable

Autonomy

Level: supervised

Escalation Triggers:

error_rate > 5

Tradeoffs

Prefer	Over	Reason
reliability	throughput	integration failures can cascade across systems

Safety

Action	Permission	Cooldown	Max Auto
publish_message	`autonomous`	-	-
publish_no_subscribers	`autonomous`	-	-
sharded_publish	`autonomous`	-	-
subscribe_to_channels	`autonomous`	-	-
subscribe_pattern	`autonomous`	-	-
receive_message	`autonomous`	-	-
receive_pattern_match	`autonomous`	-	-
sharded_subscribe	`autonomous`	-	-
unsubscribe_from_channels	`autonomous`	-	-
unsubscribe_from_patterns	`autonomous`	-	-
exit_subscription_mode	`autonomous`	-	-
sharded_unsubscribe	`autonomous`	-	-
command_in_subscription_mode	`autonomous`	-	-
ping_while_subscribed	`autonomous`	-	-
pubsub_channels	`autonomous`	-	-
pubsub_numsub	`autonomous`	-	-
pubsub_numpat	`autonomous`	-	-

Extensions (framework-specific hints)

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

Pub Sub Messaging Blueprint

Actors

Fields

States

Rules

Outcomes

Publish_message (Priority: 10)

Publish_no_subscribers (Priority: 11)

Sharded_publish (Priority: 12)

Subscribe_to_channels (Priority: 20)

Subscribe_pattern (Priority: 21)

Receive_message (Priority: 22)

Receive_pattern_match (Priority: 23)

Sharded_subscribe (Priority: 24)

Unsubscribe_from_channels (Priority: 30)

Unsubscribe_from_patterns (Priority: 31)

Exit_subscription_mode (Priority: 32)

Sharded_unsubscribe (Priority: 33)

Command_in_subscription_mode (Priority: 40) — Error: SUBSCRIPTION_MODE

Ping_while_subscribed (Priority: 41)

Pubsub_channels (Priority: 50)

Pubsub_numsub (Priority: 51)

Pubsub_numpat (Priority: 52)

Errors

Events

Related Blueprints

AGI Readiness

Goals

Reliable Pub Sub Messaging

Autonomy

Tradeoffs

Safety

Command_in_subscription_mode (Priority: 40) — Error: `SUBSCRIPTION_MODE`