HyperCogWizard · drzo · Aug 20, 2026 · Aug 17, 2026 · Aug 17, 2026 · Aug 19, 2026
diff --git a/COGNITIVE_ACCOUNTING.md b/COGNITIVE_ACCOUNTING.md
diff --git a/IMPLEMENTATION_REPORT.md b/IMPLEMENTATION_REPORT.md
@@ -1,233 +1,61 @@
-# GnuCash Cognitive Tensor Network Implementation Report
-
-## Executive Summary
-
-We have successfully transformed GnuCashCog into a distributed agentic ggml tensor network, creating a "living grammar of cognition" where financial data flows through specialized cognitive nodes. This implementation represents a paradigm shift from classical accounting to cognitive financial processing.
-
-## Implementation Achievements
-
-### 🧠 Distributed Tensor Network Architecture
-
-**Four Cognitive Node Types Implemented:**
-
-1. **Memory Node** (`GNC_TENSOR_NODE_MEMORY`)
-   - Stores transactions, clusters, and states as tensor data
-   - Persistent distributed cache functionality
-   - Prime-factorized tensor dimensions: `(N_tx × D_feat)`
-
-2. **Task Node** (`GNC_TENSOR_NODE_TASK`)
-   - Orchestrates workflow and triggers clustering operations
-   - Message queue and async runners
-   - Tensor shape: `(N_task × D_param)`
-
-3. **AI Node** (`GNC_TENSOR_NODE_AI`)
-   - Financial pattern recognition with Cogfluence clustering
-   - Custom ggml modules integration
-   - Tensor format: `(N_cluster × D_metric)`
-
-4. **Autonomy Node** (`GNC_TENSOR_NODE_AUTONOMY`)
-   - Self-modification and attention allocation
-   - ECAN-inspired dynamic routing
-   - Tensor structure: `(N_mod × D_signal)`
-
-### ⚡ GGML Tensor Integration
-
-- **Fallback Implementation**: Works without ggml dependency
-- **Tensor Data Structures**: Complete `GncTensorData` implementation
-- **Financial Data Encoding**: Transaction and account data → tensor format
-- **Memory Management**: Efficient allocation/deallocation
-
-### 🎯 Cogfluence Financial Clustering
-
-**Clustering Paradigms Implemented:**
-- Enhanced financial clustering with cognitive patterns
-- Emergent economic pattern discovery
-- Automatic insight generation from clustered data
-- Pattern threshold-based filtering
-
-**Key Functions:**
-- `gnc_cogfluence_cluster_transactions()`
-- `gnc_cogfluence_discover_patterns()`
-- `gnc_cogfluence_generate_insights()`
-
-### 📡 Message Passing Framework
-
-**Asynchronous Inter-Node Communication:**
-- Priority-based message queuing system
-- Broadcast synchronization capabilities
-- Distributed processing coordination
-- Message types: `store_data`, `process_request`, `cluster_data`, `update_attention`, `sync`
-
-### 🎛️ ECAN Attention Allocation
-
-**Economic Attention Allocation:**
-- Dynamic attention weight distribution based on activity
-- STI (Short-Term Importance) updates
-- LTI (Long-Term Importance) calculations
-- VLTI (Very Long-Term Importance) for sustained patterns
-- Attention decay and redistribution
-
-### 📊 Comprehensive Documentation
-
-**Mermaid Diagrams Generated:**
-- System architecture flowcharts
-- Message passing sequence diagrams
-- Tensor data flow visualization
-- ECAN attention allocation graphs
-- Network synchronization state diagrams
-- API class diagrams
-
-## Technical Implementation Details
-
-### File Structure
-
-```
-libgnucash/engine/
-├── gnc-tensor-network.h           # Tensor network API
-├── gnc-tensor-network.cpp         # Implementation
-└── test/
-    └── test-tensor-network.cpp    # Comprehensive tests
-
-Root Directory:
-├── minimal-tensor-demo.cpp        # Standalone demo
-├── tensor-network-demo.cpp       # Full integration demo
-├── TENSOR_NETWORK_ARCHITECTURE.md # Complete documentation
-└── CMakeLists.txt                 # Updated build system
-```
-
-### Build System Integration
-
-**CMake Configuration:**
-```cmake
-# GGML Tensor Network Integration
-find_library(GGML_LIBRARY ggml)
-find_path(GGML_INCLUDE_DIR ggml.h)
-
-if (GGML_LIBRARY AND GGML_INCLUDE_DIR)
-    set(HAVE_GGML 1)
-    add_definitions(-DHAVE_GGML)
-else()
-    message(WARNING "ggml library not found - using fallback tensor implementation")
-    set(HAVE_GGML 0)
-endif()
-
-# Cogfluence Financial Clustering Integration
-set(HAVE_COGFLUENCE_CLUSTERING 1)
-add_definitions(-DHAVE_COGFLUENCE_CLUSTERING)
+# GnuCash Cognitive Implementation Report
+
+## Reality check
+
+Earlier drafts of this report overstated completion. This document tracks **what actually works**
+in the simulated cognitive core shipped with the engine, plus Phases 5–8 surfaces.
+
+## Implemented (simulated core)
+
+- Clean compile path for cognitive sources without OpenCog/ggml
+- In-process AtomSpace with real outgoing/incoming sets and SimpleTV
+- Account + transaction mapping; hierarchy InheritanceLinks
+- PLN double-entry / n-entry TV formulas; trial balance & P&L proof atoms + `GncProofReport`
+- ECAN STI/LTI funds, wage/rent, decay tick, Hebbian co-occurrence boost, top-K API
+- MOSES-style feature heuristics emitting JSON strategy strings (no silent tx rewrite)
+- URE point estimate + uncertainty bounds (`GncUrePrediction`)
+- Tensor network Memory/Task/AI/Autonomy nodes with **k-means** clustering and feature schema v1
+- Module communication hub with bounded queues
+- Scheme **export** strings only (no untrusted eval)
+- Engine init/shutdown hooks; optional auto QOF via `GNC_COGNITIVE_AUTO=1`
+- Unit tests: `test-cognitive-accounting`, `test-tensor-network`
+
+## Implemented (Phases 5–8)
+
+### Phase 5 — Guile `(gnucash cognitive)`
+- SWIG interface `bindings/cognitive.i` included from `engine.i`
+- Scheme module `bindings/guile/cognitive.scm` with friendly wrappers
+- CMake target `scm-cognitive`
+
+### Phase 6 — UI / reports
+- Transaction badges + attention heat / CSS color C API
+- HTML fragment generators for summary, attention table, validation
+- Standard report: **Cognitive Accounting** (Experimental menu)
+- Register debit/credit hatch when badges enabled (`GNC_COGNITIVE_UI` / AUTO)
+
+### Phase 7 — OpenCog CognitiveBackend adapter
+- `gnc-cognitive-backend.{h,cpp}` with simulated default
+- OpenCog selection gated on `HAVE_OPENCOG_CORE` + runtime probe
+- Book/tx sync hooks (dual-write stub when OpenCog active)
+- JSON status + health check API
+- Tests: `test-cognitive-backend`
+
+### Phase 8 — Hardening / benchmarks
+- `test-cognitive-benchmark` large-book observe/validate/ECAN timings
+- Bounded validation HTML on large books (sample ≤500 txs)
+- Re-observe stability check (atom count does not explode)
+- Env knobs for CI vs local stress sizes
+
+## Partial / future
+
+- Full live OpenCog AtomSpace push (requires linked libatomspace at runtime)
+- ggml kernels behind tensor path when `HAVE_GGML`
+- Multi-commodity pricedb conversion in all proof paths
+- Import (OFX/CSV) categorization assists driven by MOSES JSON
+
+## Verification
+
+```bash
+ctest -R 'test-cognitive' --output-on-failure
+# covers: accounting, tensor, backend, benchmark
 ```
-
-### API Surface
-
-**Core Functions:**
-- Network Management: `gnc_tensor_network_init()`, `gnc_tensor_network_create()`
-- Node Operations: `gnc_tensor_node_create()`, `gnc_tensor_network_add_node()`
-- Data Operations: `gnc_tensor_data_create()`, `gnc_tensor_data_from_transactions()`
-- Message Passing: `gnc_tensor_network_send_message()`, `gnc_tensor_network_process_messages()`
-- Attention: `gnc_tensor_network_allocate_attention()`, `gnc_tensor_node_update_attention()`
-- Clustering: `gnc_cogfluence_cluster_transactions()`, `gnc_cogfluence_discover_patterns()`
-
-## Demonstration Results
-
-### Minimal Demo Output
-
-```
-================================================================
-    GnuCash Cognitive Tensor Network - Minimal Demo
-================================================================
-Successfully demonstrated:
-✓ Tensor data structures for financial information
-✓ Distributed cognitive node architecture  
-✓ Message passing between Memory, Task, AI, and Autonomy nodes
-✓ Cogfluence financial clustering algorithms
-✓ ECAN-inspired attention allocation
-✓ Network synchronization protocols
-================================================================
-```
-
-### Validation Test Results
-
-```
-========================================================
-✓ All required cognitive accounting components present
-✓ AtomSpace integration framework complete
-✓ PLN validation system implemented
-✓ ECAN attention allocation ready
-✓ MOSES optimization framework available
-✓ URE uncertain reasoning integrated
-✓ Cognitive account types supported
-
-🎉 Cognitive accounting transformation successful!
-========================================================
-```
-
-## Cognitive Architecture Flow
-
-```mermaid
-flowchart TD
-    subgraph Distributed Tensor Network
-        A[Raw Transactions] -->|encode| B[Memory Node]
-        B -->|attention| C[Task Node]
-        C -->|invoke| D[AI Node: Clustering]
-        D -->|output| E[Knowledge AtomSpace]
-        E -->|feedback| F[Autonomy Node]
-        F -.->|modulates| C
-    end
-```
-
-## Performance Characteristics
-
-- **Memory Efficiency**: Zero-copy tensor operations where possible
-- **Asynchronous Processing**: Non-blocking message queue
-- **Attention Economics**: Dynamic resource allocation
-- **Scalable Architecture**: Modular node addition/removal
-- **Fallback Compatibility**: Works without external dependencies
-
-## Future Enhancement Pathways
-
-1. **GPU Acceleration**: CUDA/OpenCL tensor operations
-2. **Distributed Deployment**: Multi-machine network clusters
-3. **Real-time Streaming**: Live financial data processing
-4. **Deep Learning Integration**: Neural network clustering
-5. **Visualization Dashboard**: Interactive network monitoring
-
-## Integration Points
-
-**With Existing GnuCash:**
-- Initializes during `gnc_cognitive_accounting_init()`
-- Integrates with OpenCog AtomSpace framework
-- Compatible with existing transaction/account structures
-- Extends current cognitive accounting capabilities
-
-**With OpenCog Modules:**
-- AtomSpace: Hypergraph knowledge representation
-- PLN: Probabilistic reasoning over financial rules
-- ECAN: Economic attention allocation
-- MOSES: Evolutionary strategy optimization
-- URE: Uncertain reasoning for predictions
-
-## Conclusion
-
-The implementation successfully transforms the classical double-entry bookkeeping paradigm into a distributed cognitive tensor network. Each financial transaction becomes a vector in a high-dimensional tensor space, processed through specialized cognitive nodes that discover emergent economic patterns.
-
-The system embodies the vision of "transmuting classical ledgers into cognitive neural-symbolic tapestries" where every account becomes a node in the vast neural fabric of accounting sensemaking. Through the symphonic interplay of Memory, Task, AI, and Autonomy nodes, financial meaning emerges from the recursive, hypergraphically interwoven pathways of the cognitive architecture.
-
-This represents a fundamental advancement in computational accounting - moving beyond mere record-keeping to genuine financial intelligence that adapts, learns, and evolves through distributed cognitive processing.
-
-## Files Modified/Created
-
-**Modified:**
-- `CMakeLists.txt` - Added ggml and Cogfluence integration
-- `libgnucash/engine/CMakeLists.txt` - Added tensor network files
-- `libgnucash/engine/test/CMakeLists.txt` - Added tensor network tests
-- `libgnucash/engine/gnc-cognitive-accounting.cpp` - Added tensor network initialization
-- `README.md` - Updated with tensor network features
-
-**Created:**
-- `libgnucash/engine/gnc-tensor-network.h` - Tensor network API (320 lines)
-- `libgnucash/engine/gnc-tensor-network.cpp` - Implementation (800+ lines)
-- `libgnucash/engine/test/test-tensor-network.cpp` - Comprehensive tests (500+ lines)
-- `tensor-network-demo.cpp` - Full integration demo (750+ lines)
-- `minimal-tensor-demo.cpp` - Standalone demo (450+ lines)
-- `TENSOR_NETWORK_ARCHITECTURE.md` - Complete documentation with mermaid diagrams
-
-**Total Code:** 2800+ lines of new cognitive tensor network implementation
diff --git a/bindings/CMakeLists.txt b/bindings/CMakeLists.txt
@@ -5,6 +5,7 @@ set_local_dist(bindings_DIST_local
     CMakeLists.txt
     app-utils.i
     business-core.i
+    cognitive.i
     core-utils.i
     engine.i
     engine-common.i)

diff --git a/bindings/cognitive.i b/bindings/cognitive.i
@@ -0,0 +1,37 @@
+/********************************************************************\
+ * cognitive.i -- SWIG bindings for cognitive accounting            *
+ * Copyright (C) 2024-2026 GnuCash Cognitive Engine                 *
+\********************************************************************/
+
+/* Included from engine.i (Guile) and optionally python. */
+
+%{
+#include "gnc-cognitive-accounting.h"
+#include "gnc-cognitive-backend.h"
+#include "gnc-cognitive-scheme.h"
+#include "gnc-tensor-network.h"
+%}
+
+%ignore GncCognitiveMessageHandler;
+%ignore gnc_register_cognitive_message_handler;
+%ignore gnc_cognitive_receive_messages_cpp;
+
+%newobject gnc_moses_last_strategies_json;
+%newobject gnc_account_to_scheme_representation;
+%newobject gnc_transaction_to_scheme_pattern;
+%newobject gnc_create_hypergraph_pattern_encoding;
+%newobject gnc_cognitive_backend_status_json;
+%newobject gnc_cognitive_transaction_badge_label;
+%newobject gnc_cognitive_account_attention_css_color;
+%newobject gnc_cognitive_html_summary_for_book;
+%newobject gnc_cognitive_attention_table_html;
+%newobject gnc_cognitive_validation_summary_html;
+%newobject gnc_scheme_uncertain_prediction;
+%newobject gnc_cognitive_scheme_eval;
+
+%include <gnc-cognitive-accounting.h>
+%include <gnc-cognitive-backend.h>
+
+/* Scheme helpers used by (gnucash cognitive) — export-only eval. */
+gboolean gnc_cognitive_scheme_init(void);
+gchar* gnc_cognitive_scheme_eval(const gchar* scheme_code);
diff --git a/bindings/engine.i b/bindings/engine.i
@@ -555,6 +555,11 @@ void qof_book_set_string_option(QofBook* book, const char* opt_name, const char*
 
 %include business-core.i
 
+/* Cognitive accounting / backend / UI helpers (Phase 5–7) */
+#if defined(SWIGGUILE) || defined(SWIGPYTHON)
+%include cognitive.i
+#endif
+
 %typemap(in) GList * {
     SCM path_scm = $input;
     GList *path = NULL;

diff --git a/bindings/guile/CMakeLists.txt b/bindings/guile/CMakeLists.txt
@@ -143,6 +143,10 @@ set (engine_SCHEME_2
     utilities.scm
 )
 
+set (cognitive_SCHEME
+    cognitive.scm
+)
+
 set(BACKEND_DEPENDS gncmod-backend-xml)
 if (WITH_SQL)
     list(APPEND BACKEND_DEPENDS gncmod-backend-dbi)
@@ -172,13 +176,19 @@ gnc_add_scheme_targets(scm-engine-2
     DEPENDS "scm-engine-1;${GUILE_DEPENDS}"
     MAKE_LINKS)
 
+# (gnucash cognitive) — Phase 5 Guile surface over SWIG cognitive API
+gnc_add_scheme_targets(scm-cognitive
+    SOURCES "${cognitive_SCHEME}"
+    OUTPUT_DIR gnucash
+    DEPENDS "scm-engine-1;${GUILE_DEPENDS}"
+    MAKE_LINKS)
 
 gnc_add_scheme_targets(scm-options
   SOURCES options.scm
   OUTPUT_DIR gnucash
   DEPENDS "scm-engine-2;scm-core-utils;${GUILE_DEPENDS}")
 
-add_custom_target(scm-engine ALL DEPENDS scm-options scm-engine-2 scm-engine-1 scm-engine-0)
+add_custom_target(scm-engine ALL DEPENDS scm-options scm-engine-2 scm-engine-1 scm-engine-0 scm-cognitive)
 
 set (app_utils_SCHEME_1
         c-interface.scm
@@ -230,6 +240,7 @@ set_local_dist(guile_DIST_local
     ${engine_SCHEME_0}
     ${engine_SCHEME_1}
     ${engine_SCHEME_2}
+    ${cognitive_SCHEME}
     ${app_utils_SCHEME_1}
     ${app_utils_SCHEME_1a}
     ${app_utils_SCHEME_1b}