passepartout/skills/org-skill-protocol-validator.org

SKILL: Communication Protocol Schema Validator (Universal Literate Note)

• Overview
• Phase A: Demand (PRD)
  • 1. Purpose
  • 2. User Needs
  • 3. Success Criteria
• Phase B: Blueprint (PROTOCOL)
  • 1. Architectural Intent
  • 2. Semantic Interfaces
• Phase D: Build (Implementation)
  • Schema Enforcement
• Registration

Overview

The Communication Protocol Schema Validator skill provides deep structural validation for all messages entering the org-agent kernel. It ensures that every property list adheres to a strict schema, preventing malformed data from causing harness-level errors.

Phase A: Demand (PRD)

1. Purpose

Enforce a formal grammar for the Org-Agent Control Protocol (communication protocol).

2. User Needs

• Type Safety: Ensure mandatory keys (e.g., `:type`, `:payload`) are present.
• Range Validation: Check that enum values (e.g., `:REQUEST`, `:EVENT`) are valid.
• Structural Integrity: Validate nested payloads based on the message type.

3. Success Criteria

• Block any message that does not contain a valid `:type`.
• Block `:REQUEST` messages that lack a `:target`.
• Block `:EVENT` messages that lack a `:payload` with an `:action` or `:sensor`.

Phase B: Blueprint (PROTOCOL)

1. Architectural Intent

Decouple protocol parsing (framing/unframing) from semantic validation.

2. Semantic Interfaces

(defun validate-communication-protocol-schema (msg)
  "Returns T if the message is valid, NIL (and signals error) otherwise.")

Phase D: Build (Implementation)

Schema Enforcement

(in-package :org-agent)

(defun validate-communication-protocol-schema (msg)
  "Strict structural validation for incoming communication protocol messages."
  (unless (listp msg)
    (error "Communication Protocol Schema Error: Message must be a property list (got ~s)" (type-of msg)))
  
  (let ((type (getf msg :type)))
    (unless (member type '(:REQUEST :EVENT :RESPONSE :LOG))
      (error "Communication Protocol Schema Error: Invalid message type '~a'" type))
    
    (case type
      (:REQUEST 
       (unless (getf msg :target)
         (error "Communication Protocol Schema Error: REQUEST missing mandatory :target"))
       (unless (getf msg :payload)
         (error "Communication Protocol Schema Error: REQUEST missing mandatory :payload")))
      
      (:EVENT
       (let ((payload (getf msg :payload)))
         (unless (and payload (listp payload))
           (error "Communication Protocol Schema Error: EVENT missing or invalid :payload"))
         (unless (or (getf payload :action) (getf payload :sensor))
           (error "Communication Protocol Schema Error: EVENT payload must contain :action or :sensor"))))
      
      (:RESPONSE
       (unless (getf msg :payload)
         (error "Communication Protocol Schema Error: RESPONSE missing mandatory :payload"))))
    
    t))

Registration

(defskill :skill-communication-protocol-validator
  :priority 95
  :trigger (lambda (ctx) (member (getf (getf ctx :payload) :sensor) '(:protocol-received)))
  :probabilistic nil
  :deterministic (lambda (action ctx)
              (declare (ignore ctx))
              (validate-communication-protocol-schema action)
              action))