Blog › ICP guides

PicoLisp developer on retainer: idx database index, Pilog logic programming, OOP with class/dm, server-side GUI, and PicoLisp platform engineering on monthly retainer

October 23, 2026 · ~17 min read

A PicoLisp application managing customer records was returning wrong entries on 3 queries per day. The system used PicoLisp’s built-in idx balanced binary tree to index customer records by name for O(log n) ordered retrieval. A developer had implemented the comparison function as (de cmpName (A B) (< A B)) — a less-than predicate using PicoLisp’s built-in < comparison operator. The PicoLisp developer on retainer diagnosed the root cause: PicoLisp’s < operator returns NIL for equal values (correct strict less-than behavior), but the comparison function was inadvertently returning T for equal keys in contexts where the string comparison reached equal-length equal-content strings. The idx data structure requires a strict total order: for any two distinct keys A and B, exactly one of (cmp A B) or (cmp B A) must be true, and for equal keys both must be NIL. When the comparison function violated this contract at equal-key boundaries, the idx traversal algorithm followed both child branches, causing it to visit nodes on incorrect subtree paths and return entries that did not match the query key. The fix replaced the comparison function with a strict version that returns NIL for equal keys and added a (=T (db +Customer 'name lookup-key)) pre-check before invoking idx traversal to confirm the target external symbol exists in the database. Wrong entries: 3 per day → 0.

The work log entry read “fixed database query bug, 14h.” It names the symptom and the duration. It cannot explain to a client why the fix required understanding PicoLisp’s idx balanced binary tree traversal algorithm, why the comparison function contract matters for tree correctness, why a correct <=T guard matters for external symbol existence checking (PicoLisp’s =T tests whether a value is literally the atom T, not just non-NIL), or what the relationship is between idx tree nodes, db external symbols, and PicoLisp’s persistent object database. The 14 hours of comparison function analysis (tracing the idx traversal with equal-key inputs to observe which subtree path was selected), tree structure inspection (using PicoLisp’s interactive REPL to examine the idx node layout), comparison function redesign (replacing the single < call with a correct strict comparison that handles equal-length strings), and pre-check addition (adding the (=T (db ...)) guard before traversal entry) are not visible in the diff beyond the corrected comparison function and the added guard.

PicoLisp’s idx database, external symbols, and OOP system

PicoLisp’s built-in database is not a separate subsystem — it is the language itself applied to persistent storage. The core abstraction is the external symbol: a PicoLisp symbol whose name begins with + (in the 64-bit PicoLisp implementation) or whose identifier is prefixed with { in other encodings. External symbols are stored on disk in a database file (the “pool”) and loaded into memory on demand using a demand-paging mechanism. When a PicoLisp program accesses a property of an external symbol that has not yet been loaded, the runtime transparently loads it from the pool file. This means the entire PicoLisp object database is addressed through the normal symbol property mechanism — (get Sym 'property) to read a property, (put Sym 'property Value) to write one, (put! Sym 'property Value) for persistent write that marks the symbol dirty for the next commit. The commit function flushes all modified external symbols to the pool file atomically; rollback discards all pending changes by reloading modified symbols from the pool. This gives PicoLisp a transactional persistence model with no separate ORM layer.

The idx function maintains a balanced binary search tree stored in a symbol’s property list. The call (idx 'RootProp Value T) inserts Value into the tree rooted at the RootProp property of the current object (using PicoLisp’s * and ** tree node encoding). The call (idx 'RootProp Value NIL) retrieves the node matching Value. The tree ordering is determined by PicoLisp’s built-in comparison operator < applied to the values stored in the tree. The correctness invariant: for any two values A and B stored in the tree, (< A B) must return T if and only if A strictly precedes B in the intended order, and NIL for equal values. PicoLisp’s < operator compares numbers numerically, strings lexicographically, and symbols by identity. For string comparison, (< "abc" "abc") correctly returns NIL. The traversal bug occurred not in the comparison function itself but in a wrapper that called (if (< A B) T NIL) — which returns NIL for equal strings, correct — but then also used (not (= A B)) as a fallback that was incorrectly returning T for a specific class of transient symbols that PicoLisp represents as anonymous @-prefixed values. The lesson: (= A B) in PicoLisp tests object identity (the same memory cell), not value equality. For string value equality, (= A B) between two string literals may return NIL even when they contain identical characters, because they are distinct string objects. The correct value-equality test for strings is (equal A B) (or the shorthand (== A B) in some PicoLisp dialects, though in standard PicoLisp == is pointer equality, not deep equality — use equal for structural comparison).

PicoLisp’s OOP system is built on the same symbol-property mechanism as the database. A class in PicoLisp is a symbol (conventionally named with a leading +) whose property list contains method definitions, class variables, and superclass references. The class function (or the equivalent (de +ClassName ...) idiom) defines a class symbol. Methods are defined using dm (define method): (dm methodName> (.) expression) defines a method named methodName> (PicoLisp convention: method names end with >) on the current class (*Class is the dynamically scoped current class during class/extend bodies). The receiver object is available as This inside method bodies. The msg function sends a message (invokes a method) dynamically: (msg This 'methodName> ...args) finds the method by traversing the class hierarchy of This upward from its direct class. The extend function adds methods to an existing class without redefining it: (extend +ExistingClass) (dm newMethod> ...) ) is the idiom for adding methods to a class defined in another file or library. Slot declarations use rel (for relationship slots that hold references to other objects) and var (for value slots that hold direct data). The new function creates a new instance: (new '(+ClassName) 'slotName slotValue ...).

Transient symbols are PicoLisp symbols that exist only for the duration of a program run and are garbage-collected when no longer referenced. They are written in source code with a leading @ or using the box function. External symbols (database objects) persist across runs and are identified by their pool file offset. The distinction matters for idx trees: inserting transient symbols into an idx tree alongside external symbols produces a mixed tree where the ordering of transient vs external symbols under < comparison may be implementation-defined (PicoLisp compares symbols by their cell address, which differs between runs for transient symbols). A production idx tree should contain only external symbols, or only transient symbols, never a mixture. When a developer accidentally inserts both types — for example, by mixing query-result transient symbols with stored external symbols in the same index — the tree ordering becomes non-deterministic across server restarts, producing the intermittent wrong-entry queries that prompted the retainer engagement.

Pilog logic programming, the gui framework, and PicoLisp package system

Pilog is PicoLisp’s embedded Prolog-style logic programming sublanguage. Pilog facts and rules are declared using be: (be factName (Arg1 Arg2) goalBody ...) defines a Horn clause. The left-hand side specifies the predicate name and argument pattern (with PicoLisp uppercase variables for unification variables). The right-hand side is a sequence of Pilog goals that must all succeed for the clause to succeed. Goals are PicoLisp expressions where function calls of the form (funcName Arg1 Arg2) are evaluated by calling the named PicoLisp function; goals of the form (be predName ...) invoke other Pilog predicates recursively. The pilog function evaluates a Pilog query and invokes a callback for each solution: (pilog '((predName @Var)) (println @Var)). The solve function collects all solutions into a list: (solve '((predName @Var)) @Var) returns a list of all bindings of @Var that satisfy the goal. The select function is PicoLisp’s database-aware Pilog query function: it iterates over external symbols matching a set of database predicates in an order that minimizes memory loading, making it the correct choice for querying large persistent databases rather than pilog which may load the entire database into memory.

Pilog unification variables are written with a leading @ in Pilog goal bodies: @Var, @Result, @Name. Unification (= in standard Prolog) is performed implicitly by Pilog’s pattern-matching engine when a be clause is applied to a goal. Pilog arithmetic uses the is/2 predicate to evaluate PicoLisp expressions: (is @Sum (+ @A @B)) evaluates the PicoLisp expression (+ @A @B) (with @A and @B bound to their current values) and unifies the result with @Sum. Pilog cut is (!): placing (!) in a goal body commits to the current clause choice and discards remaining backtracking alternatives. Negation as failure: (not goal) succeeds if goal fails. PicoLisp’s Pilog system integrates with the db function for database queries: (db +ClassName 'slotName Value) is a Pilog goal that retrieves the external symbol of class +ClassName whose slotName slot equals Value. Combining db goals with custom be predicates is the primary pattern for building PicoLisp database applications with declarative query logic.

The PicoLisp gui web framework generates HTML server-side, with each interactive component (button, field, text input, selection list) corresponding to a PicoLisp session-scoped GUI object. A gui form is defined by calling GUI component constructors inside a form expression: (form NIL (gui '(+Button) "Submit" do-action)) creates a form containing a button that invokes do-action when clicked. The turnpage function commits the current page state and generates the HTML response; rollback aborts the current transaction and reloads all modified external symbols from the pool, providing form-level transaction semantics. The gui framework is stateful: each browser session corresponds to a PicoLisp server process with its own heap, and the session-local GUI objects track form state between HTTP requests. This architecture requires careful management of (commit) and (rollback) calls to ensure that user-initiated actions that modify database objects either fully commit or fully revert. The connect function establishes a socket connection to another PicoLisp server process, enabling multi-process PicoLisp architectures where a front-end application server delegates database operations to a dedicated database server process running in a separate PicoLisp instance.

PicoLisp’s namespace system uses packages: a package is a PicoLisp source file that begins with a (symbols ‘packageName ‘pico) call, making packageName the current package and importing all symbols from the pico base package. Symbols defined in a package are prefixed with the package name when accessed from outside: packageName~symbolName. The de function defines a function in the current package. The load function loads a PicoLisp source file, executing its top-level expressions. PicoLisp’s fundamental data types: numbers (fixed-point with configurable scale), symbols (atoms with property lists), and pairs (cons cells forming lists). List construction: (cons A B), (list A B C). List access: (car X) for head, (cdr X) for tail, (cadr X) for second element. List processing: (mapcar fn lst) for mapping, (mapc fn lst) for side-effecting iteration, (filter pred lst) for selection, (extract fn lst) for mapping-with-filter (returns only non-NIL results). Quoting: (quote X) or ‘X prevents evaluation. The let form binds local variables: (let (A 1 B 2) (+ A B)). The with form binds This to an object for property access: (with customerObj (get This ‘name)) is equivalent to (get customerObj ‘name) but makes the object the implicit receiver for all property operations in the body.

How HourTab tracks PicoLisp developer retainer hours

PicoLisp retainer work shares the invisible-work problem with all database platform retainers, with the additional challenge that PicoLisp’s integrated database/logic/GUI stack makes the boundaries between layers invisible to clients who see only the application behavior. Fixing an idx comparison function is a diff that changes one comparison expression; the value is correct database traversal for all future queries. Adding a be clause to a Pilog predicate is a diff with one new declaration; the value is correct logical inference for a query case that was previously returning stale or missing results. Extending a class with extend +PremiumClass and adding a dm calculate-price> method override is a diff with three lines; the value is correct method dispatch for all premium customer objects. Adding a (rollback) call at a transaction abort point is a diff with one function call; the value is consistent database state for all sessions that hit the error path.

HourTab gives PicoLisp developers a public retainer-hours URL they send to clients — typically research institutions running PicoLisp for AI and logic programming applications, industrial systems using PicoLisp’s built-in database for embedded device management, and small development teams building PicoLisp web applications using the integrated GUI framework — at the start of an engagement. For PicoLisp retainers, each work log entry should name the mechanism (idx comparison function audit; idx traversal correctness repair; db external symbol access pattern redesign; (commit)/(rollback) transaction boundary placement; +Entity class hierarchy extension with rel/var slot additions; be Pilog clause declaration and goal pipeline composition; pilog/solve/select query pipeline restructuring; class/extend OOP hierarchy design; dm method dispatch chain repair; msg dynamic dispatch tracing; new object construction and val/put/get slot accessor design; gui web framework form and session design; turnpage request dispatch; rollback multi-step transaction abort; connect inter-process server communication), the specific function or method name and the database or logic problem, and the before/after observable metric. PicoLisp retainers are often compared to Prolog developer retainers for logic programming work, to Scheme developer retainers for Lisp-family language work, and to Factor developer retainers for minimalist language platform engineering. The distinction from Prolog is the integrated database: PicoLisp’s db/idx system gives Pilog queries direct access to persistent object storage with demand-paged external symbols, whereas SWI-Prolog requires a separate database interface. HourTab’s work log makes the idx traversal repair and Pilog predicate redesign visible to clients who would otherwise see only the symptom — wrong query results — and not understand why the fix required understanding PicoLisp’s comparison contract and symbol identity semantics.

FAQ: PicoLisp developer retainers