memex/notes/org-skill-org-delivery.org

SKILL: Org-Native Delivery Agent (Universal Literate Note)

• Overview
• Phase A: Demand (PRD)
  • 1. Purpose
  • 2. User Needs
  • 3. Success Criteria
    • Queue Appending Verification
    • Channel-specific ID Resolution
    • Org Timestamp Formatting Accuracy
• Phase B: Blueprint (PROTOCOL)
• Phase B: Blueprint (PROTOCOL)
  • 1. Architectural Intent
  • 2. Semantic Interfaces (Lisp Signatures)

Overview

The Org-Native Delivery Agent is the primary outbound actuator for external messaging. It uses the "Inbox-as-a-Queue" pattern, enqueuing structured Org-mode headlines for external bridges (Signal, Telegram, etc.).

Phase A: Demand (PRD)

1. Purpose

Define the interfaces for asynchronous external message enqueuing.

2. User Needs

• Asynchronous Dispatch: Persistence via `delivery.org` file.
• Multi-Channel Support: Routing to Signal, Telegram, Discord.
• Structured Provenance: Timestamped entries with recipient IDs.

3. Success Criteria

TODO Queue Appending Verification

TODO Channel-specific ID Resolution

TODO Org Timestamp Formatting Accuracy

Phase B: Blueprint (PROTOCOL)

Phase B: Blueprint (PROTOCOL)

1. Architectural Intent

The Org-Native Delivery Agent will function as a stateless message queuing system. It receives message envelopes as Lisp data structures, persists them to a designated Org-mode file (`delivery.org`), and returns upon successful enqueuing. External bridge processes are responsible for consuming messages from `delivery.org` and handling delivery to specific channels. This decoupling ensures resilience and scalability. We favor simplicity and robustness over complex routing logic within the Agent itself. The Org file acts as a source of truth for queued messages, enabling auditing and recovery.

2. Semantic Interfaces (Lisp Signatures)

#+BEGIN_SRC lisp ;;; Signature: `org-delivery-enqueue' ;;; ;;; Enqueues a message for delivery. ;;; ;;; Arguments: ;;; `recipient-id`: Channel-specific identifier (e.g., Signal number, Telegram chat ID). STRING. ;;; `channel`: Keyword indicating the target channel. SYMBOL (one of: :signal, :telegram, :discord, …). ;;; `message-body`: The content of the message. STRING. Can contain Org-mode markup. ;;; `properties`: A plist of additional metadata. LIST (plist). ;;; ;;; Returns: A plist containing `:status :success` or `:status :failure` with an optional `:error-message`. ;;; Upon success: returns a message id. ;;; Upon failure: returns `:error-message`. ;;; (defun org-delivery-enqueue (recipient-id channel message-body &optional properties)