Module message_queue 

Deferred-message storage for agents queue {add, list, read id}.

Mirrors the sqlite predecessor’s split: a message_queue row carries either an agent_instance_hierarchy or an agent_tag (CHECK enforces); the master message_queue_contents registry has FK-cascade chains down to per-kind tables (message_queue_texts, message_queue_images, message_queue_audios, message_queue_videos, message_queue_files) — one DELETE on message_queue sweeps every per-kind row through the cascades.

Structs

DrainedMessage

One drained message — carries enough metadata to re-INSERT the original row.

Enums

ContentRow

One content row — typed payload of a single message_queue_contents.id.

DeleteOutcome

Outcome of a delete_by_id attempt. Distinguishes the three terminal states the handler must surface differently: the row was soft-deleted, no active row matched the id, or the row exists but the caller isn’t authorized to delete it.

DeliveryTarget

One addressed delivery target.

ResolvedTarget

List all queued message_queue visible under parent. Three rules:

Functions

check_any_pending

EXISTS-check: are any queue rows in scope for target_hierarchy?

content_row_to_part

Map one ContentRow to its matching SDK RichContentPart variant.

delete_by_id

Atomically soft-delete the message_queue row with the given id (flips active = FALSE) and return its reconstructed shape — but only when caller_agent_instance_hierarchy is the row’s sender or an ancestor of it. The authorization decision happens inside the transaction, before the flip, so an unauthorized attempt leaves the row untouched.

enqueue_with_content

Atomic enqueue: inserts the message_queue row, walks content and extracts every part into a per-kind table referenced by id, then UPDATEs the message_queue.content column with the assembled [ResponseContent] JSON (One(i64) for single-part, Many(Vec<i64>) for multi-part). Returns the new message_queue.id. Everything runs inside one transaction — failure rolls every content row back.

list_delivery_targets

Enumerate every delivery target with pending queue rows in the subtree rooted at parent:

list_pending_for_targets

Stream every active = TRUE message_queue row for any of targets, JOINed against message_queue_contents for parts. Grouped per-parent so parts reflects the relational content shape, not a JSON shadow. Pagination is by message_queue_contents.id (the --after-id / --limit scope is on parts, not rows — but the row boundary stays stable per parent).

read_content

Look up a single content row by message_queue_contents.id. Returns None when the id doesn’t exist; a per-kind miss is DB corruption and surfaces as Error::InvalidData.

read_pending_and_upgrade_tag

Non-destructive read of every queue row in scope for an agent, fused with the tag-group upgrade. Two-rule predicate: direct hierarchy match OR BOUND-tag match.

subscribe_delivered

Wait until the message_queue row identified by id has been consumed — i.e. its active column has flipped from TRUE to FALSE. Resolves Ok(()) the moment the flip is observed, regardless of which path performed it.