#+TITLE: SKILL: Protocol Validator (org-skill-protocol-validator.org)
#+AUTHOR: Agent
#+FILETAGS: :system:protocol:validation:
#+PROPERTY: header-args:lisp :tangle ../lisp/security-validator.lisp

* Overview
The Protocol Validator enforces schema compliance on every message entering or leaving the cognitive pipeline. It checks that messages are valid plists, that they have the required ~:type~ and ~:payload~ fields, and that the type is one of the known types (~:REQUEST~, ~:EVENT~, ~:RESPONSE~, ~:LOG~, ~:STATUS~). This prevents malformed messages from crashing the pipeline and ensures backward compatibility when the protocol evolves.

* Architectural Intent

The Protocol Validator wraps ~validate-communication-protocol-schema~
(the core communication function) in a skill-level gate. It is the first
filter every message passes through — malformed messages are rejected
before they reach any cognitive stage.

** Contract

1. (validator-protocol-check msg): returns ~msg~ if valid per
   ~validate-communication-protocol-schema~. Signals ~error~ on
   malformed messages (caught by the skill's deterministic gate).
2. The skill's deterministic gate wraps the validator: valid actions pass
   through; invalid actions produce a ~:LOG~ rejection with
   ~:level :error~.

** Boundaries

- Does NOT define the schema — that is ~core-communication.org~.
- Does NOT validate semantic content — that is the Bouncer and Policy.

* Implementation

** Package Context
#+begin_src lisp
(in-package :passepartout)
#+end_src

** Validation Logic
;; REPL-VERIFIED: 2026-05-03T13:00:00
#+begin_src lisp
(defun validator-protocol-check (msg)
  "Enforces structural schema compliance on protocol messages."
  (validate-communication-protocol-schema msg))
#+end_src

** Skill Registration
#+begin_src lisp
(defskill :passepartout-security-validator
  :priority 95
  :trigger (lambda (ctx) (declare (ignore ctx)) t)
  :deterministic (lambda (action ctx)
                   (declare (ignore ctx))
                   (handler-case
                       (progn (validator-protocol-check action) action)
                     (error (c)
                       (list :type :LOG :payload (list :level :error :text (format nil "Protocol Violation: ~a" c)))))))
#+end_src

* Test Suite

#+begin_src lisp
(eval-when (:compile-toplevel :load-toplevel :execute)
  (ql:quickload :fiveam :silent t))

(defpackage :passepartout-security-validator-tests
  (:use :cl :fiveam :passepartout)
  (:export #:validator-suite))

(in-package :passepartout-security-validator-tests)

(def-suite validator-suite :description "Verification of the Protocol Validator")
(in-suite validator-suite)

(test test-validator-passes-valid-message
  "Contract 1: a valid message passes protocol check."
  (let ((msg '(:type :EVENT :payload (:sensor :heartbeat))))
    (handler-case
        (progn
          (validator-protocol-check msg)
          (pass))
      (error (c)
        (fail "Validator rejected a valid message: ~a" c)))))

(test test-validator-rejects-missing-type
  "Contract 1: a message missing :type is rejected."
  (let ((msg '(:payload (:sensor :heartbeat))))
    (signals error
      (validator-protocol-check msg))))
#+end_src