Amr Gharbeia
e2d1d9ac8f
Some checks failed
Deploy-Agent-V15-Stdin / JOB-V15-STDIN (push) Failing after 2s
92 lines
3.5 KiB
Org Mode
92 lines
3.5 KiB
Org Mode
:PROPERTIES:
|
|
:ID: org-skill-communication-protocol-validator
|
|
:CREATED: [2026-04-12 Sun 14:35]
|
|
:END:
|
|
#+TITLE: SKILL: Communication Protocol Schema Validator (Universal Literate Note)
|
|
#+STARTUP: content
|
|
#+FILETAGS: :protocol:communication-protocol:security:validation:autonomy:
|
|
|
|
* Overview
|
|
The *Communication Protocol Schema Validator* skill provides deep structural validation for all messages entering the opencortex kernel. It ensures that every property list adheres to a strict schema, preventing malformed data from causing harness-level errors.
|
|
|
|
* Phase A: Demand (PRD)
|
|
:PROPERTIES:
|
|
:STATUS: SIGNED
|
|
:END:
|
|
|
|
** 1. Purpose
|
|
Enforce a formal grammar for the OpenCortex 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)
|
|
:PROPERTIES:
|
|
:STATUS: SIGNED
|
|
:END:
|
|
|
|
** 1. Architectural Intent
|
|
Decouple protocol parsing (framing/unframing) from semantic validation.
|
|
|
|
** 2. Semantic Interfaces
|
|
|
|
#+begin_src lisp
|
|
(defun validate-communication-protocol-schema (msg)
|
|
"Returns T if the message is valid, NIL (and signals error) otherwise.")
|
|
#+end_src
|
|
|
|
* Phase D: Build (Implementation)
|
|
|
|
** Schema Enforcement
|
|
#+begin_src lisp :tangle ../src/communication-validator.lisp
|
|
(in-package :opencortex)
|
|
|
|
(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 (let ((raw (proto-get msg :type))) (if (keywordp raw) (intern (string-upcase (string raw)) :keyword) raw))))
|
|
(unless (member type '(:REQUEST :EVENT :RESPONSE :LOG :STATUS))
|
|
(error "Communication Protocol Schema Error: Invalid message type '~a'" type))
|
|
|
|
(case type
|
|
(:REQUEST
|
|
(unless (proto-get msg :target)
|
|
(error "Communication Protocol Schema Error: REQUEST missing mandatory :target"))
|
|
(unless (proto-get msg :payload)
|
|
(error "Communication Protocol Schema Error: REQUEST missing mandatory :payload")))
|
|
|
|
(:EVENT
|
|
(let ((payload (proto-get msg :payload)))
|
|
(unless (and payload (listp payload))
|
|
(error "Communication Protocol Schema Error: EVENT missing or invalid :payload"))
|
|
(unless (or (proto-get payload :action) (proto-get payload :sensor))
|
|
(error "Communication Protocol Schema Error: EVENT payload must contain :action or :sensor"))))
|
|
|
|
(:RESPONSE
|
|
(unless (proto-get msg :payload)
|
|
(error "Communication Protocol Schema Error: RESPONSE missing mandatory :payload"))))
|
|
|
|
t))
|
|
#+end_src
|
|
|
|
* Registration
|
|
#+begin_src lisp :tangle ../src/communication-validator.lisp
|
|
(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))
|
|
#+end_src
|