#+PROPERTY: header-args:lisp :tangle (expand-file-name "package.lisp" (concat (or (getenv "INSTALL_DIR") ".") "/harness"))
#+TITLE: System Interface (package.lisp)
#+AUTHOR: Amr
#+FILETAGS: :harness:interface:
#+STARTUP: content

* System Interface (package.lisp)

The ~package.lisp~ file defines the public API of the ~opencortex~ harness. It serves as the primary membrane between the deterministic core modules and the dynamic world of skills and actuators.

** Public API Export

#+begin_src lisp
(defpackage :opencortex
  (:use :cl)
  (:export
   ;; --- communication protocol ---
   #:frame-message
   #:read-framed-message
   #:PROTO-GET
   #:LIST-OBJECTS-WITH-ATTRIBUTE
   #:COSINE-SIMILARITY
   #:VAULT-MASK-STRING
   #:*VAULT-MEMORY*
   #:parse-message
   #:make-hello-message
   #:validate-communication-protocol-schema

   ;; --- Daemon Lifecycle ---
   #:start-daemon
   #:stop-daemon
   #:harness-log
   #:main

   ;; --- Diagnostic Doctor ---
   #:doctor-run-all
   #:doctor-main
   #:doctor-check-dependencies
   #:doctor-check-env

   ;; --- Setup Wizard ---
   #:register-provider
   #:system-ready-p
   #:run-setup-wizard

   ;; --- Gateway Manager Skill ---
   #:skill-gateway-register
   #:skill-gateway-link
   #:gateway-manager-main

   ;; --- Diagnostic Doctor ---
   #:doctor-run-all
   #:doctor-main

   ;; --- Memory (CLOSOS) ---
   #:ingest-ast
   #:lookup-object
   #:list-objects-by-type
   #:org-id-new
   #:*memory*
   #:*history-store*
   #:org-object
   #:make-org-object
   #:org-object-id
   #:org-object-type
   #:org-object-attributes
   #:org-object-parent-id
   #:org-object-children
   #:org-object-version
   #:org-object-last-sync
   #:org-object-vector
   #:org-object-content
   #:org-object-hash
   #:snapshot-memory
   #:rollback-memory

   ;; --- Context API (Peripheral Vision) ---
   #:context-query-store
   #:context-get-active-projects
   #:context-get-recent-completed-tasks
   #:context-list-all-skills
   #:context-get-skill-source
   #:context-get-system-logs
   #:context-resolve-path
   #:context-get-skill-telemetry
   #:harness-track-telemetry
   #:context-assemble-global-awareness

   ;; --- Reactive Signal Pipeline ---
   #:process-signal
   #:perceive-gate
   #:probabilistic-gate
   #:consensus-gate
   #:act-gate
   #:reason-gate
   #:perceive-gate
   #:dispatch-gate
   #:inject-stimulus
   #:initialize-actuators
   #:dispatch-action
   #:register-actuator

   ;; --- Skill Engine ---
   #:load-skill-from-org
   #:initialize-all-skills
   #:load-skill-with-timeout
   #:topological-sort-skills
   #:validate-lisp-syntax
   #:defskill
   #:*skills-registry*
   #:skill
   #:skill-name
   #:skill-priority
   #:skill-dependencies
   #:skill-trigger-fn
   #:skill-probabilistic-prompt
   #:skill-deterministic-fn

   ;; --- Tool Registry ---
   #:def-cognitive-tool
   #:*cognitive-tools*

   ;; --- Engineering Standards Skill ---
   #:verify-git-clean-p

   ;; --- Literate Programming Skill ---
   #:literate-check-block-balance
   #:check-tangle-sync
   #:*tangle-targets*

   ;; --- Emacs Edit Skill ---
   #:emacs-edit-read-file
   #:emacs-edit-write-file
   #:emacs-edit-add-headline
   #:emacs-edit-set-property
   #:emacs-edit-set-todo
   #:emacs-edit-find-headline-by-id
   #:emacs-edit-find-headline-by-title
   #:emacs-edit-generate-id
   #:emacs-edit-id-format
   #:emacs-edit-ast-to-org
   #:emacs-edit-modify

   ;; --- Lisp Utils Skill ---
   #:lisp-utils-validate
   #:lisp-utils-check-structural
   #:lisp-utils-check-syntactic
   #:lisp-utils-check-semantic
   #:lisp-utils-register

   ;; --- Config Manager & Diagnostics Skill ---
   #:register-provider
   #:save-providers
   #:configure-provider
   #:run-setup-wizard
   #:get-oc-config-dir
   #:prompt-for
   #:save-secret
   #:doctor-check-dependencies
   #:doctor-check-xdg
   #:doctor-check-llm
   #:doctor-run-all

   ;; --- Tool Permissions Skill ---
   #:get-tool-permission
   #:set-tool-permission
   #:check-tool-permission-gate
   #:cognitive-tool
   #:cognitive-tool-name
   #:cognitive-tool-description
   #:cognitive-tool-parameters
   #:cognitive-tool-guard
   #:cognitive-tool-body

   ;; --- Emacs Client Registry ---
   #:*emacs-clients*
   #:*clients-lock*
   #:register-emacs-client
   #:unregister-emacs-client

   ;; --- Probabilistic Engine ---
   #:ask-probabilistic
   #:register-probabilistic-backend
   #:distill-prompt
   #:*provider-cascade*

   ;; --- Security Vault ---
   #:vault-get-secret
   #:vault-set-secret

   ;; --- Deterministic Logic ---
   #:list-objects-with-attribute
   #:deterministic-verify

   ;; --- AST Helpers ---
   #:find-headline-missing-id))
#+end_src

* Package Implementation

#+begin_src lisp
(in-package :opencortex)
#+end_src

** Robust Plist Accessor

#+begin_src lisp
(defun proto-get (plist key)
  "Robustly retrieves a value from a plist, checking both uppercase and lowercase keyword versions."
  (let* ((s (string key))
         (up (intern (string-upcase s) :keyword))
         (dn (intern (string-downcase s) :keyword)))
    (or (getf plist up) (getf plist dn))))
#+end_src

** Harness Logging State

The harness maintains a thread-safe circular log buffer to provide context for debugging and neural reasoning.

#+begin_src lisp
(defvar *system-logs* nil)
(defvar *logs-lock* (bordeaux-threads:make-lock "harness-logs-lock"))
(defvar *max-log-history* 100)
#+end_src

** Skills Registry

#+begin_src lisp
(defvar *skills-registry* (make-hash-table :test 'equal)
  "Global registry of all loaded skills.")
#+end_src

** Skill Telemetry State

#+begin_src lisp
(defvar *skill-telemetry* (make-hash-table :test 'equal))
(defvar *telemetry-lock* (bordeaux-threads:make-lock "harness-telemetry-lock"))
#+end_src

** Telemetry Implementation

The system tracks the performance and reliability of individual skills.

#+begin_src lisp
(defun harness-track-telemetry (skill-name duration status)
  "Updates performance metrics for a specific skill. Status should be :success or :rejected."
  (when skill-name
    (bordeaux-threads:with-lock-held (*telemetry-lock*)
      (let ((entry (or (gethash skill-name *skill-telemetry*) (list :executions 0 :total-time 0 :failures 0))))
        (incf (getf entry :executions))
        (incf (getf entry :total-time) duration)
        (when (eq status :rejected) (incf (getf entry :failures)))
        (setf (gethash skill-name *skill-telemetry*) entry)))))
#+end_src

** Cognitive Tool Registry

The Tool Registry allows the agent to interact with the physical world. Every tool must define a guard (for security) and a body (for execution).

#+begin_src lisp
(defvar *cognitive-tools* (make-hash-table :test 'equal))

(defstruct cognitive-tool
  name
  description
  parameters
  guard
  body)

(defmacro def-cognitive-tool (name description parameters &key guard body)
  "Registers a new cognitive tool into the global registry. Parameters must be a list of property lists."
  `(setf (gethash (string-downcase (string ',name)) *cognitive-tools*)
         (make-cognitive-tool :name (string-downcase (string ',name))
                              :description ,description
                              :parameters ',parameters
                              :guard ,guard
                              :body ,body)))
#+end_src

** Harness Logging Implementation

Centralized logging function. It simultaneously writes to standard output and the in-memory circular buffer.

#+begin_src lisp
(defun harness-log (msg &rest args)
  "Centralized logging for the harness."
  (let ((formatted-msg (apply #'format nil msg args)))
    (bordeaux-threads:with-lock-held (*logs-lock*)
      (push formatted-msg *system-logs*)
      (when (> (length *system-logs*) *max-log-history*)
        (setq *system-logs* (subseq *system-logs* 0 *max-log-history*))))
    (format t "~a~%" formatted-msg)
    (finish-output)))
#+end_src
* Global Test Runner
#+begin_src lisp :tangle (expand-file-name "run-all-tests.lisp" (concat (or (getenv "INSTALL_DIR") ".") "/harness"))
(load (merge-pathnames "quicklisp/setup.lisp" (user-homedir-pathname)))

(let ((oc-dir (or (uiop:getenv "OC_DATA_DIR") 
                  (namestring (truename "./")))))
  (push (uiop:ensure-directory-pathname oc-dir) asdf:*central-registry*))

(progn
  (ql:quickload :opencortex :silent t)
  (finish-output))

(format t "~%=== Initializing Skills BEFORE loading tests ===~%")
(finish-output)
(opencortex:initialize-all-skills)

(format t "~%=== Loading Test System ===~%")
(finish-output)
(progn
  (ql:quickload :opencortex/tests :silent t)
  (finish-output))

(format t "~%=== Running ALL Test Suites ===~%")
(finish-output)

(let ((suites '(("ENGINEERING-STANDARDS" . "OPENCORTEX-ENGINEERING-STANDARDS-TESTS::ENGINEERING-STANDARDS-SUITE")
                ("LITERATE-PROGRAMMING" . "OPENCORTEX-LITERATE-PROGRAMMING-TESTS::LITERATE-PROGRAMMING-SUITE")
                ("COMMUNICATION" . "OPENCORTEX-COMMUNICATION-TESTS::COMMUNICATION-PROTOCOL-SUITE")
                ("PIPELINE" . "OPENCORTEX-PIPELINE-TESTS::PIPELINE-SUITE")
                ("BOOT" . "OPENCORTEX-BOOT-TESTS::BOOT-SUITE")
                ("MEMORY" . "OPENCORTEX-MEMORY-TESTS::MEMORY-SUITE")
                ("IMMUNE" . "OPENCORTEX-IMMUNE-SYSTEM-TESTS::IMMUNE-SUITE")
                ("EMACS-EDIT" . "OPENCORTEX-EMACS-EDIT-TESTS::EMACS-EDIT-SUITE")
                ("LISP-UTILS" . "OPENCORTEX-LISP-UTILS-TESTS::LISP-UTILS-SUITE")
                ("SELF-EDIT" . "OPENCORTEX-SELF-EDIT-TESTS::SELF-EDIT-SUITE")
                ("TOOL-PERMISSIONS" . "OPENCORTEX-TOOL-PERMISSIONS-TESTS::TOOL-PERMISSIONS-SUITE")
                ("CONFIG" . "OPENCORTEX-CONFIG-MANAGER-TESTS::CONFIG-SUITE")
                ("DIAGNOSTICS" . "OPENCORTEX-DIAGNOSTICS-TESTS::DIAGNOSTICS-SUITE"))))
  (dolist (suite suites)
    (let ((pkg (intern (string-upcase (car (uiop:split-string (cdr suite) :separator "::"))) :keyword)))
      (when (find-package pkg)
        (format t "~&--- Suite: ~A ---~%" (car suite))
        (fiveam:run! (uiop:safe-read-from-string (cdr suite)))))))

(format t "~%=== ALL TESTS COMPLETE ===~%")
#+end_src