Update class comments for PqDatabase and PqCursor

Add codec-related documentation:
- PqDatabase: codec API, collaborators, examples, implementation notes
- PqCursor: codec methods, collaborators, codec iteration example

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: mumez

repository/PunQLite-DB/PqCursor.class.st

@@ -7,11 +7,13 @@ Responsibility:
 - Enable seeking to specific keys with exact match, greater-than, or less-than semantics
 - Allow reading and deletion of entries at the current cursor position
 - Implement standard Smalltalk enumeration protocol (do:, reverseDo:)
+- Support codec-based value decoding during iteration
 
 Collaborators:
-- PqDatabase: The database I iterate over, provides handle and settings
+- PqDatabase: The database I iterate over, provides handle, settings, and codec
 - UnQLiteFFI: Makes low-level cursor FFI calls (init, seek, next, prev, release)
 - UnQLiteFetchCallback: Used for callback-based data retrieval
+- PqCodec: Decodes values when using codec-aware retrieval methods
 - UnQLiteConstants: Provides cursor positioning constants (CURSOR_MATCH_*)
 
 Public API and Key Messages:
@@ -25,6 +27,8 @@ Public API and Key Messages:
 - #seek:untilEndDo: - Seek to key and iterate forward from there
 - #currentKey, #currentValue - Read data at current position
 - #currentStringKey, #currentStringValue - Read as strings
+- #currentValueIntoDecoded: - Read and decode value using database's codec
+- #currentValueInto:by: - Read and decode value using specified codec
 - #deleteCurrent - Delete entry at current position
 - #close - Release cursor resources
 
@@ -42,6 +46,14 @@ Example:
       ""Iterates over 'banana' and 'cherry'""
       Transcript show: c currentStringKey; cr]].
 
+  ""Codec-based iteration""
+  db := PqDatabase openOnMemory.
+  db codec: PqJsonCodec new.
+  db storeAt: 'data' valueEncoded: #('a' 'b' 'c').
+  db cursorDo: [:cursor |
+    cursor do: [:c |
+      c currentValueIntoDecoded: [:value | Transcript show: value printString; cr]]].
+
 Internal Representation:
 - database - The PqDatabase being iterated
 - handle - Native unqlite_kv_cursor* pointer (inherited from PqObject)
@@ -55,6 +67,7 @@ Implementation Points:
 - CURSOR_MATCH_GE and CURSOR_MATCH_LE provide range query support
 - Callback-based retrieval is available via #currentKeyInto: and #currentValueInto:
 - Buffer size for key/value retrieval defaults to database's fetchBufferSize
+- Codec for decoding is obtained from the associated database instance
 "
 Class {
 	#name : #PqCursor,

repository/PunQLite-DB/PqDatabase.class.st

@@ -8,13 +8,15 @@ Responsibility:
 - Create and manage cursors for efficient iteration
 - Provide access to Jx9 scripting engine and JSON document collections
 - Handle data marshalling between Smalltalk objects and byte arrays
+- Support pluggable codecs for transparent object serialization
 
 Collaborators:
 - UnQLiteFFI: Makes low-level FFI calls for all database operations
 - PqCursor: Created via #newCursor for efficient database iteration
 - PqCollection: Created via #collectionName: for JSON document storage
 - PqJx9Executer: Created via #jx9 for Jx9 script execution
 - PqValueAppender: Created via #appenderAt: for efficient value appending
+- PqCodec: Encodes/decodes values (PqUtf8Codec, PqJsonCodec, PqFuelCodec)
 - UnQLiteConstants: Provides mode constants and return codes
 
 Public API and Key Messages:
@@ -28,6 +30,11 @@ Public API and Key Messages:
 - #newCursor - Create a cursor for efficient scanning
 - #transact: - Execute a block within a manual transaction
 - #close - Close database and release native resources
+- #codec, #codec: - Get/set the codec for value encoding/decoding
+- #storeAt:valueEncoded: - Store a value using the default codec
+- #fetchAt:intoDecoded: - Fetch and decode a value using the default codec
+- #storeAt:value:by: - Store a value using a specified codec
+- #fetchAt:into:by: - Fetch and decode a value using a specified codec
 
 Example:
   ""Basic key-value operations""
@@ -44,9 +51,17 @@ Example:
   db cursorDo: [:cursor |
     cursor do: [:c | Transcript show: c currentStringKey, ' => ', c currentStringValue; cr]].
 
+  ""Using codec for object serialization""
+  db := PqDatabase openOnMemory.
+  db codec: PqJsonCodec new.
+  db storeAt: 'users' valueEncoded: #('Alice' 'Bob' 'Charlie').
+  db fetchAt: 'users' intoDecoded: [:users | users do: [:u | Transcript show: u; cr]].
+  db close.
+
 Internal Representation:
 - Inherits handle from PqObject - points to unqlite* database handle
 - handleIsValid - tracks whether database is open
+- codec - PqCodec instance for value encoding/decoding (lazy initialized)
 
 Implementation Points:
 - Keys and values are stored as byte arrays (UTF-8 for strings)
@@ -56,6 +71,7 @@ Implementation Points:
 - Always call #close to release native resources (use #ensure: in production)
 - Cursors become invalid after database modifications
 - Fetch operations may need larger buffer sizes for large values (see #fetchBufferSize:)
+- Default codec is PqUtf8Codec, configurable via PqSettings>>defaultCodecClassName
 "
 Class {
 	#name : #PqDatabase,