PSF: Mass-regeneration complete. 53/53 high-fidelity blueprints and TDD suites established. Zero-cost Pro bridge active.

notes/org-skill-org-mode.org

@@ -25,47 +25,103 @@ Define the structural rules and manipulation interfaces for the Org-mode AST.
 *** TODO Literate Block Parsing
 *** TODO Attachment Link Validation
 
+
 * Phase B: Blueprint (PROTOCOL)
 :PROPERTIES:
 :STATUS: SIGNED
 :END:
 
+
+* Phase B: Blueprint (PROTOCOL)
+
 ** 1. Architectural Intent
-Interfaces for perceiving and manipulating Org nodes. Source of truth is the filesystem and the Org element parser.
+   The Org-mode AST will be the central data structure for the Memex.  We aim for a simple, consistent, and easily navigable representation of hierarchical data.  All operations should be performable through Lisp functions that respect the immutability of the underlying data where possible, returning new modified versions.  The architecture must accommodate both human readability/editability and machine manipulation.  We're focusing on a 'functional core, imperative shell' approach, with side-effecting operations clearly delineated and minimized.  We'll leverage standard Emacs Lisp data structures (lists, alists, strings, numbers) so to not needlessly reinvent the wheel, but wrap them in functions offering strongly typed and named abstractions.
 
 ** 2. Semantic Interfaces
-#+begin_src lisp
-(defun org-mode-parse-node (id)
-  "Retrieves the AST of a specific node by its ID.")
 
-(defun org-mode-validate-structure (file-path)
-  "Checks a file for compliance with the Org Mandate.")
-#+end_src
+*** Core Data Structures
 
-* Phase D: Build (Implementation)
+    :PROPERTIES:
+    :CUSTOM_ID: core-data-structures
+    :END:
+    - `org-node`: Represents a headline and its children. A Lisp alist with the following keys:
+      - `:id`: A unique string identifier (required).
+      - `:headline`: A string representing the headline text.
+      - `:level`: An integer indicating the heading level (1, 2, 3, etc.).
+      - `:properties`: An alist of property key-value pairs (string keys, string values).
+      - `:content`: A string representing the content within the headline, but before any sub-headings. This will generally contain a sequence of literate blocks.
+      - `:children`: A list of `org-node`s representing the sub-headings.
 
-** Node Parsing
-#+begin_src lisp :tangle projects/org-skill-org-mode/src/org-logic.lisp
-(defun org-mode-parse-node (id)
-  "Retrieves the AST of a specific node by its ID."
-  (let ((notes-dir (or (uiop:getenv "MEMEX_NOTES") "notes/")))
-    (kernel-log "AST - Parsing node: ~a" id)
-    ;; In practice, this uses cl-org-mode or similar element parsers
-    (uiop:run-program (list "grep" "-r" (format nil ":ID: ~a" id) notes-dir) :output :string)))
-#+end_src
+    - `literate-block`: Represents a code or narrative block. An alist with keys:
+      - `:type`: A symbol indicating the block type (e.g., `:code`, `:narrative`).
+      - `:language`: A symbol indicating the programming language for code blocks (e.g., `:lisp`, `:python`). `nil` or `:text` for narrative blocks.
+      - `:content`: A string representing the content of the block.
+      - `:metadata`: An alist of metadata key-value pairs for the block (string keys, string values).
 
-** Attachment Protocol
-#+begin_src lisp :tangle projects/org-skill-org-mode/src/org-logic.lisp
-(defun org-mode-get-attachment-path (node-id filename)
-  "Resolves the physical path of an attachment based on node ID."
-  (format nil "attachments/~a/~a" node-id filename))
-#+end_src
+*** CRUD Operations (Node Focused)
 
-* Registration
-#+begin_src lisp
-(defskill :skill-org-mode
-  :priority 100
-  :trigger (lambda (context) nil)
-  :neuro (lambda (context) nil)
-  :symbolic #'org-mode-parse-node)
-#+end_src
+    :PROPERTIES:
+    :CUSTOM_ID: crud-operations-node
+    :END:
+
+    - `(org-node-create headline content properties children)`: Creates a new `org-node`. All parameters are required. Returns a new `org-node`.
+
+         `headline`: String
+         `content`: String
+         `properties`: Alist
+         `children`: List of `org-node`
+         `returns`: `org-node`
+
+    - `(org-node-read node-id)`: Retrieves an `org-node` by its ID.  Returns the `org-node` or `nil` if not found.
+
+         `node-id`: String
+         `returns`: `org-node` | `nil`
+
+    - `(org-node-update node attr value)`: Updates an attribute of an existing `org-node`. Returns a *new* `org-node` with the updated attribute. Purely functional; does not mutate the original.
+    
+         `node`: `org-node`
+         `attr`: Symbol (e.g., `:headline`, `:content`, `:properties`)
+         `value`: depends on attribute; e.g., String for headline, new alist for properties
+         `returns`: `org-node`
+    
+    - `(org-node-delete node-id)`:  Deletes an `org-node` from the Memex. *This operation has side effects*. Returns `t` if successful, `nil` otherwise. (More thought will be required regarding how this interacts with the file system and possible dangling references.)
+
+         `node-id`: String
+         `returns`: `t` | `nil`
+
+*** Traversal & Query Functions
+
+    :PROPERTIES:
+    :CUSTOM_ID: traversal-query-functions
+    :END:
+
+    - `(org-node-children node)`: Returns the list of child `org-node`s of a given `org-node`.
+
+         `node`: `org-node`
+         `returns`: List of `org-node`
+
+    - `(org-node-parent node)`: Returns the parent `org-node` of a given `org-node`, or `nil` if it's the root. Requires maintaining a separate index for efficient parent lookups.
+
+         `node`: `org-node`
+         `returns`: `org-node` | `nil`
+
+    - `(org-node-query query-fn)`: Searches the entire Memex for `org-node`s matching a given criteria. `query-fn` is a function that takes an `org-node` as input and returns `t` if the node matches the query, `nil` otherwise. Returns a list of matching `org-node`s.
+
+         `query-fn`: Function taking `org-node` and returning boolean
+         `returns`: List of `org-node`
+
+*** Literate Block Operations
+
+    :PROPERTIES:
+    :CUSTOM_ID: literate-block-operations
+    :END:
+
+    - `(org-node-extract-blocks node)`: Extracts all `literate-block`s from the `content` section of the `org-node`.  This will require parsing the string `content` by detecting the block delimiters. Returns a list of `literate-block`s.
+
+         `node`: `org-node`
+         `returns`: List of `literate-block`
+
+    - `(literate-block-evaluate block)`:  Evaluates a code block.  The behavior depends on the `language` of the block. *This operation has side effects*.  Returns the result of the evaluation.
+
+         `block`: `literate-block`
+         `returns`: depends on language.