CHORE: Prepare for Signal Gateway implementation

literate/core.org

@@ -28,16 +28,52 @@ graph TD
 (in-package :org-agent)
 #+end_src
 
-** Global Kernel State
-The kernel maintains several thread-safe global variables for logging, telemetry, and execution control.
+** System Logs
+Rolling buffer of kernel diagnostics.
 
 #+begin_src lisp :tangle ../src/core.lisp
 (defvar *system-logs* nil)
+#+end_src
+
+** Logs Lock
+Thread-safety for logging operations.
+
+#+begin_src lisp :tangle ../src/core.lisp
 (defvar *logs-lock* (bt:make-lock "kernel-logs-lock"))
+#+end_src
+
+** Max Log History
+The maximum number of diagnostic lines to retain in memory.
+
+#+begin_src lisp :tangle ../src/core.lisp
 (defvar *max-log-history* 100)
+#+end_src
+
+** Interrupt Flag
+Atomic flag used to halt the reasoning loop.
+
+#+begin_src lisp :tangle ../src/core.lisp
 (defvar *interrupt-flag* nil)
+#+end_src
+
+** Interrupt Lock
+Thread-safety for loop interruption.
+
+#+begin_src lisp :tangle ../src/core.lisp
 (defvar *interrupt-lock* (bt:make-lock "kernel-interrupt-lock"))
+#+end_src
+
+** Skill Telemetry
+Hash table tracking execution metrics per skill.
+
+#+begin_src lisp :tangle ../src/core.lisp
 (defvar *skill-telemetry* (make-hash-table :test 'equal))
+#+end_src
+
+** Telemetry Lock
+Thread-safety for metric updates.
+
+#+begin_src lisp :tangle ../src/core.lisp
 (defvar *telemetry-lock* (bt:make-lock "kernel-telemetry-lock"))
 #+end_src
 

literate/neurosymbolic.org

@@ -22,14 +22,24 @@ This module handles the interaction with Large Language Models, providing a unif
 (defun get-env (var &optional default) (or (uiop:getenv var) default))
 #+end_src
 
-** Authentication Registry
+** Auth Providers Registry
 Tracks API keys and authentication functions for various providers.
 
 #+begin_src lisp :tangle ../src/neuro.lisp
 (defvar *auth-providers* (make-hash-table :test 'equal))
+#+end_src
 
+** Register Auth Provider
+Registers a function or list to provide authentication for a specific backend.
+
+#+begin_src lisp :tangle ../src/neuro.lisp
 (defun register-auth-provider (name fn) (setf (gethash name *auth-providers*) fn))
+#+end_src
 
+** Get Provider Auth
+Retrieves authentication credentials for a provider, falling back to environment variables if not found in the registry.
+
+#+begin_src lisp :tangle ../src/neuro.lisp
 (defun get-provider-auth (provider)
   "Retrieves authentication credentials for a provider."
   (let ((auth (gethash provider *auth-providers*)))
@@ -50,15 +60,31 @@ Tracks API keys and authentication functions for various providers.
                  (list :api-key legacy)))))))))
 #+end_src
 
-** Backend Registry and Cascade
-The kernel supports a "cascade" of providers. If the primary provider (e.g. OpenRouter) fails, it automatically falls back to the secondary (e.g. Gemini).
+** Neuro Backends Registry
+Tracks the actual implementation functions for each LLM provider.
 
 #+begin_src lisp :tangle ../src/neuro.lisp
 (defvar *neuro-backends* (make-hash-table :test 'equal))
+#+end_src
+
+** Provider Cascade
+The ordered list of backends to attempt for neural reasoning.
+
+#+begin_src lisp :tangle ../src/neuro.lisp
 (defvar *provider-cascade* '(:openrouter :gemini))
+#+end_src
 
+** Register Neuro Backend
+Maps a keyword identifier to a backend implementation function.
+
+#+begin_src lisp :tangle ../src/neuro.lisp
 (defun register-neuro-backend (name fn) (setf (gethash name *neuro-backends*) fn))
+#+end_src
 
+** Model Selector Function
+A hook for dynamic model selection based on the current context.
+
+#+begin_src lisp :tangle ../src/neuro.lisp
 (defvar *model-selector-fn* nil "A function called with (provider context) to return a model ID.")
 #+end_src
 

literate/protocol.org

@@ -16,10 +16,18 @@ We begin by ensuring we are in the correct package.
 (in-package :org-agent)
 #+end_src
 
+** Actuator Registry
+Global registry mapping target keywords to their physical actuator functions.
+
 #+begin_src lisp :tangle ../src/protocol.lisp
 (defvar *actuator-registry* (make-hash-table :test 'equal)
   "Global registry mapping target keywords to their physical actuator functions.")
+#+end_src
 
+** Actuator Registration
+Registers an actuator function. Actuators receive two arguments: (ACTION CONTEXT).
+
+#+begin_src lisp :tangle ../src/protocol.lisp
 (defun register-actuator (name fn) 
   "Registers an actuator function. Actuators receive two arguments: (ACTION CONTEXT)."
   (setf (gethash name *actuator-registry*) fn))