From 6c1bf84c6adeac98733dca2f1f9c0e6ca72badf6 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 24 Nov 2025 03:24:39 +0000
Subject: [PATCH 01/11] Initial plan


From 653900079fdc30730c5a1546c08a5e5257c36203 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 24 Nov 2025 03:32:44 +0000
Subject: [PATCH 02/11] Add comprehensive JSDoc documentation to tsds.mts

Co-authored-by: hzhangxyz <11623447+hzhangxyz@users.noreply.github.com>
---
 tsds/tsds.mts | 282 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 282 insertions(+)

diff --git a/tsds/tsds.mts b/tsds/tsds.mts
index a377561..754d57b 100644
--- a/tsds/tsds.mts
+++ b/tsds/tsds.mts
@@ -1,3 +1,8 @@
+/**
+ * TypeScript wrapper for a deductive system implemented in WebAssembly.
+ * Provides classes and functions for working with logical terms, rules, and inference.
+ */
+
 import create_ds from "./ds.mjs";
 import type * as dst from "./ds.d.mts";
 
@@ -5,6 +10,18 @@ const ds: dst.EmbindModule = await create_ds();
 
 let _buffer_size: number = 1024;
 
+/**
+ * Get or set the default buffer size used for string conversions.
+ *
+ * @param size - The new buffer size to set. If 0 (default), the current size is returned without modification.
+ * @returns The previous buffer size value.
+ *
+ * @example
+ * ```typescript
+ * const currentSize = buffer_size(); // Get current size
+ * const oldSize = buffer_size(2048); // Set new size, returns old size
+ * ```
+ */
 export function buffer_size(size: number = 0): number {
     const old_size = _buffer_size;
     if (size !== 0) {
@@ -13,11 +30,19 @@ export function buffer_size(size: number = 0): number {
     return old_size;
 }
 
+/**
+ * Common interface for all deductive system types.
+ * @internal
+ */
 interface Common {
     clone(): Common;
     data_size(): number;
 }
 
+/**
+ * Static methods interface for deductive system types.
+ * @internal
+ */
 interface StaticCommon<T extends Common> {
     from_binary(buffer: dst.Buffer): T;
     to_binary(value: T): dst.Buffer;
@@ -25,13 +50,30 @@ interface StaticCommon<T extends Common> {
     to_string(value: T, size: number): string;
 }
 
+/**
+ * Valid initialization arguments for deductive system types.
+ * @internal
+ */
 type InitialArgument<T extends Common> = _common_t<T> | T | string | dst.Buffer | null;
 
+/**
+ * Base class for all deductive system wrapper types.
+ * Handles initialization, serialization, and common operations.
+ * @internal
+ */
 class _common_t<T extends Common> {
     type: StaticCommon<T>;
     value: T;
     capacity: number;
 
+    /**
+     * Creates a new instance.
+     *
+     * @param type - The static type interface for this common type.
+     * @param value - Initial value (can be another instance, base value, string, or buffer).
+     * @param size - Optional buffer size for string initialization.
+     * @throws {Error} If initialization fails or invalid arguments provided.
+     */
     constructor(type: StaticCommon<T>, value: InitialArgument<T>, size: number = 0) {
         this.type = type;
         if (value instanceof _common_t) {
@@ -60,6 +102,12 @@ class _common_t<T extends Common> {
         }
     }
 
+    /**
+     * Convert the value to a string representation.
+     *
+     * @returns The string representation.
+     * @throws {Error} If conversion fails.
+     */
     toString(): string {
         const result = this.type.to_string(this.value, buffer_size());
         if (result === "") {
@@ -68,69 +116,203 @@ class _common_t<T extends Common> {
         return result;
     }
 
+    /**
+     * Get the binary representation of the value.
+     *
+     * @returns The binary data as a Buffer.
+     */
     data(): dst.Buffer {
         return this.type.to_binary(this.value);
     }
 
+    /**
+     * Get the size of the data in bytes.
+     *
+     * @returns The data size.
+     */
     size(): number {
         return this.value.data_size();
     }
 
+    /**
+     * Create a deep copy of this instance.
+     *
+     * @returns A new instance with cloned value.
+     */
     copy(): this {
         const this_constructor = this.constructor as new (value: T, size: number) => this;
         return new this_constructor(this.value.clone() as T, this.size());
     }
 
+    /**
+     * Get a key representation for this value (same as toString).
+     *
+     * @returns The string key.
+     */
     key(): string {
         return this.toString();
     }
 }
 
+/**
+ * Wrapper class for deductive system strings.
+ * Supports initialization from strings, buffers, or other instances.
+ *
+ * @example
+ * ```typescript
+ * const str1 = new string_t("hello");
+ * const str2 = new string_t(str1.data()); // From binary
+ * console.log(str1.toString()); // "hello"
+ * ```
+ */
 export class string_t extends _common_t<dst.String> {
+    /**
+     * Creates a new string instance.
+     *
+     * @param value - Initial value (string, buffer, or another string_t).
+     * @param size - Optional buffer size for string initialization.
+     * @throws {Error} If initialization fails.
+     */
     constructor(value: InitialArgument<dst.String>, size: number = 0) {
         super(ds.String, value, size);
     }
 }
 
+/**
+ * Wrapper class for logical variables in the deductive system.
+ * Variables are used in logical terms and can be unified.
+ *
+ * @example
+ * ```typescript
+ * const var1 = new variable_t("X");
+ * console.log(var1.name().toString()); // "X"
+ * ```
+ */
 export class variable_t extends _common_t<dst.Variable> {
+    /**
+     * Creates a new variable instance.
+     *
+     * @param value - Initial value (string, buffer, or another variable_t).
+     * @param size - Optional buffer size for string initialization.
+     * @throws {Error} If initialization fails.
+     */
     constructor(value: InitialArgument<dst.Variable>, size: number = 0) {
         super(ds.Variable, value, size);
     }
 
+    /**
+     * Get the name of this variable.
+     *
+     * @returns The variable name as a string_t.
+     */
     name(): string_t {
         return new string_t(this.value.name());
     }
 }
 
+/**
+ * Wrapper class for items in the deductive system.
+ * Items represent constants or functors in logical terms.
+ *
+ * @example
+ * ```typescript
+ * const item = new item_t("atom");
+ * console.log(item.name().toString()); // "atom"
+ * ```
+ */
 export class item_t extends _common_t<dst.Item> {
+    /**
+     * Creates a new item instance.
+     *
+     * @param value - Initial value (string, buffer, or another item_t).
+     * @param size - Optional buffer size for string initialization.
+     * @throws {Error} If initialization fails.
+     */
     constructor(value: InitialArgument<dst.Item>, size: number = 0) {
         super(ds.Item, value, size);
     }
 
+    /**
+     * Get the name of this item.
+     *
+     * @returns The item name as a string_t.
+     */
     name(): string_t {
         return new string_t(this.value.name());
     }
 }
 
+/**
+ * Wrapper class for lists in the deductive system.
+ * Lists contain ordered sequences of terms.
+ *
+ * @example
+ * ```typescript
+ * const list = new list_t("[a, b, c]");
+ * console.log(list.length()); // 3
+ * console.log(list.getitem(0).toString()); // "a"
+ * ```
+ */
 export class list_t extends _common_t<dst.List> {
+    /**
+     * Creates a new list instance.
+     *
+     * @param value - Initial value (string, buffer, or another list_t).
+     * @param size - Optional buffer size for string initialization.
+     * @throws {Error} If initialization fails.
+     */
     constructor(value: InitialArgument<dst.List>, size: number = 0) {
         super(ds.List, value, size);
     }
 
+    /**
+     * Get the number of elements in the list.
+     *
+     * @returns The list length.
+     */
     length(): number {
         return this.value.length();
     }
 
+    /**
+     * Get an element from the list by index.
+     *
+     * @param index - The zero-based index of the element.
+     * @returns The term at the specified index.
+     */
     getitem(index: number): term_t {
         return new term_t(this.value.getitem(index));
     }
 }
 
+/**
+ * Wrapper class for logical terms in the deductive system.
+ * A term can be a variable, item, or list.
+ *
+ * @example
+ * ```typescript
+ * const term = new term_t("f(X, a)");
+ * const innerTerm = term.term(); // Get the underlying term type
+ * ```
+ */
 export class term_t extends _common_t<dst.Term> {
+    /**
+     * Creates a new term instance.
+     *
+     * @param value - Initial value (string, buffer, or another term_t).
+     * @param size - Optional buffer size for string initialization.
+     * @throws {Error} If initialization fails.
+     */
     constructor(value: InitialArgument<dst.Term>, size: number = 0) {
         super(ds.Term, value, size);
     }
 
+    /**
+     * Get the underlying term as its specific type (variable, item, or list).
+     *
+     * @returns The term as a variable_t, item_t, or list_t.
+     * @throws {Error} If the term type is unexpected.
+     */
     term(): variable_t | item_t | list_t {
         const term_type: dst.TermType = this.value.get_type();
         if (term_type === ds.TermType.Variable) {
@@ -144,6 +326,13 @@ export class term_t extends _common_t<dst.Term> {
         }
     }
 
+    /**
+     * Ground this term with another term using unification.
+     *
+     * @param other - The term to unify with.
+     * @param scope - Optional scope string for variable naming.
+     * @returns The grounded term, or null if unification fails.
+     */
     ground(other: term_t, scope: string = ""): term_t | null {
         const capacity = buffer_size();
         const term = ds.Term.ground(this.value, other.value, scope, capacity);
@@ -154,23 +343,64 @@ export class term_t extends _common_t<dst.Term> {
     }
 }
 
+/**
+ * Wrapper class for logical rules in the deductive system.
+ * A rule consists of a conclusion and zero or more premises.
+ *
+ * @example
+ * ```typescript
+ * const rule = new rule_t("parent(X, Y) :- father(X, Y)");
+ * console.log(rule.conclusion().toString()); // "parent(X, Y)"
+ * console.log(rule.length()); // Number of premises
+ * ```
+ */
 export class rule_t extends _common_t<dst.Rule> {
+    /**
+     * Creates a new rule instance.
+     *
+     * @param value - Initial value (string, buffer, or another rule_t).
+     * @param size - Optional buffer size for string initialization.
+     * @throws {Error} If initialization fails.
+     */
     constructor(value: InitialArgument<dst.Rule>, size: number = 0) {
         super(ds.Rule, value, size);
     }
 
+    /**
+     * Get the number of premises in the rule.
+     *
+     * @returns The number of premises.
+     */
     length(): number {
         return this.value.length();
     }
 
+    /**
+     * Get a premise term by index.
+     *
+     * @param index - The zero-based index of the premise.
+     * @returns The premise term at the specified index.
+     */
     getitem(index: number): term_t {
         return new term_t(this.value.getitem(index));
     }
 
+    /**
+     * Get the conclusion (head) of the rule.
+     *
+     * @returns The conclusion term.
+     */
     conclusion(): term_t {
         return new term_t(this.value.conclusion());
     }
 
+    /**
+     * Ground this rule with another rule using unification.
+     *
+     * @param other - The rule to unify with.
+     * @param scope - Optional scope string for variable naming.
+     * @returns The grounded rule, or null if unification fails.
+     */
     ground(other: rule_t, scope: string = ""): rule_t | null {
         const capacity = buffer_size();
         const rule = ds.Rule.ground(this.value, other.value, scope, capacity);
@@ -180,6 +410,12 @@ export class rule_t extends _common_t<dst.Rule> {
         return new rule_t(rule, capacity);
     }
 
+    /**
+     * Match this rule with another rule.
+     *
+     * @param other - The rule to match against.
+     * @returns The matched rule, or null if matching fails.
+     */
     match(other: rule_t): rule_t | null {
         const capacity = buffer_size();
         const rule = ds.Rule.match(this.value, other.value, capacity);
@@ -190,29 +426,75 @@ export class rule_t extends _common_t<dst.Rule> {
     }
 }
 
+/**
+ * Search engine for the deductive system.
+ * Manages a knowledge base of rules and performs logical inference.
+ *
+ * @example
+ * ```typescript
+ * const search = new search_t();
+ * search.add("parent(john, mary)");
+ * search.add("parent(X, Y) :- father(X, Y)");
+ * search.execute((rule) => {
+ *   console.log(rule.toString());
+ *   return true; // Continue search
+ * });
+ * ```
+ */
 export class search_t {
     _search: dst.Search;
 
+    /**
+     * Creates a new search engine instance.
+     *
+     * @param limit_size - Maximum number of rules/facts in the knowledge base (default: 1000).
+     * @param buffer_size - Buffer size for internal operations (default: 10000).
+     */
     constructor(limit_size: number = 1000, buffer_size: number = 10000) {
         this._search = new ds.Search(limit_size, buffer_size);
     }
 
+    /**
+     * Set the maximum number of rules/facts the search engine can hold.
+     *
+     * @param limit_size - The new limit size.
+     */
     set_limit_size(limit_size: number): void {
         this._search.set_limit_size(limit_size);
     }
 
+    /**
+     * Set the buffer size for internal operations.
+     *
+     * @param buffer_size - The new buffer size.
+     */
     set_buffer_size(buffer_size: number): void {
         this._search.set_buffer_size(buffer_size);
     }
 
+    /**
+     * Reset the search engine, clearing all rules and facts.
+     */
     reset(): void {
         this._search.reset();
     }
 
+    /**
+     * Add a rule or fact to the knowledge base.
+     *
+     * @param text - The rule or fact as a string.
+     * @returns True if successfully added, false otherwise.
+     */
     add(text: string): boolean {
         return this._search.add(text);
     }
 
+    /**
+     * Execute the search engine with a callback for each inferred rule.
+     *
+     * @param callback - Function called for each candidate rule. Return true to continue, false to stop.
+     * @returns The number of rules processed.
+     */
     execute(callback: (candidate: rule_t) => boolean): number {
         return this._search.execute((candidate: dst.Rule): boolean => {
             return callback(new rule_t(candidate).copy());

From 7893d9d932c7b251f668c99b02a3299dd8c1f0e9 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 24 Nov 2025 03:34:00 +0000
Subject: [PATCH 03/11] Improve JSDoc clarity based on code review feedback

Co-authored-by: hzhangxyz <11623447+hzhangxyz@users.noreply.github.com>
---
 tsds/tsds.mts | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/tsds/tsds.mts b/tsds/tsds.mts
index 754d57b..218bd0b 100644
--- a/tsds/tsds.mts
+++ b/tsds/tsds.mts
@@ -11,7 +11,8 @@ const ds: dst.EmbindModule = await create_ds();
 let _buffer_size: number = 1024;
 
 /**
- * Get or set the default buffer size used for string conversions.
+ * Gets the current buffer size, or sets a new buffer size and returns the previous value.
+ * The buffer size is used for string conversions in the deductive system.
  *
  * @param size - The new buffer size to set. If 0 (default), the current size is returned without modification.
  * @returns The previous buffer size value.
@@ -308,7 +309,7 @@ export class term_t extends _common_t<dst.Term> {
     }
 
     /**
-     * Get the underlying term as its specific type (variable, item, or list).
+     * Extracts the underlying term and returns it as its concrete type (variable_t, item_t, or list_t).
      *
      * @returns The term as a variable_t, item_t, or list_t.
      * @throws {Error} If the term type is unexpected.
@@ -327,7 +328,7 @@ export class term_t extends _common_t<dst.Term> {
     }
 
     /**
-     * Ground this term with another term using unification.
+     * Ground this term with another term using unification (substitute variables with concrete values).
      *
      * @param other - The term to unify with.
      * @param scope - Optional scope string for variable naming.
@@ -395,7 +396,7 @@ export class rule_t extends _common_t<dst.Rule> {
     }
 
     /**
-     * Ground this rule with another rule using unification.
+     * Ground this rule with another rule using unification (substitute variables with concrete values).
      *
      * @param other - The rule to unify with.
      * @param scope - Optional scope string for variable naming.

From 62a0243bb95decfc033589f4b45e3a3239562287 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 24 Nov 2025 04:02:53 +0000
Subject: [PATCH 04/11] Fix JSDoc comments based on reviewer feedback

Co-authored-by: hzhangxyz <11623447+hzhangxyz@users.noreply.github.com>
---
 tsds/tsds.mts | 38 ++++++++++++++++++++------------------
 1 file changed, 20 insertions(+), 18 deletions(-)

diff --git a/tsds/tsds.mts b/tsds/tsds.mts
index 218bd0b..267b51a 100644
--- a/tsds/tsds.mts
+++ b/tsds/tsds.mts
@@ -12,7 +12,7 @@ let _buffer_size: number = 1024;
 
 /**
  * Gets the current buffer size, or sets a new buffer size and returns the previous value.
- * The buffer size is used for string conversions in the deductive system.
+ * The buffer size is used for string conversions and internal storage of terms, rules, and other objects.
  *
  * @param size - The new buffer size to set. If 0 (default), the current size is returned without modification.
  * @returns The previous buffer size value.
@@ -72,7 +72,7 @@ class _common_t<T extends Common> {
      *
      * @param type - The static type interface for this common type.
      * @param value - Initial value (can be another instance, base value, string, or buffer).
-     * @param size - Optional buffer size for string initialization.
+     * @param size - Optional buffer capacity for the internal storage.
      * @throws {Error} If initialization fails or invalid arguments provided.
      */
     constructor(type: StaticCommon<T>, value: InitialArgument<T>, size: number = 0) {
@@ -146,7 +146,8 @@ class _common_t<T extends Common> {
     }
 
     /**
-     * Get a key representation for this value (same as toString).
+     * Get a key representation for this value.
+     * The key equality is consistent with object equality.
      *
      * @returns The string key.
      */
@@ -249,7 +250,7 @@ export class item_t extends _common_t<dst.Item> {
  *
  * @example
  * ```typescript
- * const list = new list_t("[a, b, c]");
+ * const list = new list_t("(a b c)");
  * console.log(list.length()); // 3
  * console.log(list.getitem(0).toString()); // "a"
  * ```
@@ -292,7 +293,7 @@ export class list_t extends _common_t<dst.List> {
  *
  * @example
  * ```typescript
- * const term = new term_t("f(X, a)");
+ * const term = new term_t("(f X a)");
  * const innerTerm = term.term(); // Get the underlying term type
  * ```
  */
@@ -328,11 +329,11 @@ export class term_t extends _common_t<dst.Term> {
     }
 
     /**
-     * Ground this term with another term using unification (substitute variables with concrete values).
+     * Ground this term using a dictionary to substitute variables with values.
      *
-     * @param other - The term to unify with.
-     * @param scope - Optional scope string for variable naming.
-     * @returns The grounded term, or null if unification fails.
+     * @param other - A term representing a dictionary (list of pairs). Each pair contains a variable and its substitution value.
+     * @param scope - Optional scope string for variable scoping.
+     * @returns The grounded term, or null if grounding fails.
      */
     ground(other: term_t, scope: string = ""): term_t | null {
         const capacity = buffer_size();
@@ -350,8 +351,8 @@ export class term_t extends _common_t<dst.Term> {
  *
  * @example
  * ```typescript
- * const rule = new rule_t("parent(X, Y) :- father(X, Y)");
- * console.log(rule.conclusion().toString()); // "parent(X, Y)"
+ * const rule = new rule_t("(father X Y)\n----------\n(parent X Y)\n");
+ * console.log(rule.conclusion().toString()); // "(parent X Y)"
  * console.log(rule.length()); // Number of premises
  * ```
  */
@@ -396,11 +397,11 @@ export class rule_t extends _common_t<dst.Rule> {
     }
 
     /**
-     * Ground this rule with another rule using unification (substitute variables with concrete values).
+     * Ground this rule using a dictionary to substitute variables with values.
      *
-     * @param other - The rule to unify with.
-     * @param scope - Optional scope string for variable naming.
-     * @returns The grounded rule, or null if unification fails.
+     * @param other - A rule representing a dictionary (list of pairs). Each pair contains a variable and its substitution value.
+     * @param scope - Optional scope string for variable scoping.
+     * @returns The grounded rule, or null if grounding fails.
      */
     ground(other: rule_t, scope: string = ""): rule_t | null {
         const capacity = buffer_size();
@@ -412,7 +413,8 @@ export class rule_t extends _common_t<dst.Rule> {
     }
 
     /**
-     * Match this rule with another rule.
+     * Match this rule with another rule using unification.
+     * This performs pattern matching and unification between the two rules.
      *
      * @param other - The rule to match against.
      * @returns The matched rule, or null if matching fails.
@@ -434,8 +436,8 @@ export class rule_t extends _common_t<dst.Rule> {
  * @example
  * ```typescript
  * const search = new search_t();
- * search.add("parent(john, mary)");
- * search.add("parent(X, Y) :- father(X, Y)");
+ * search.add("(parent john mary)");
+ * search.add("(father X Y)\n----------\n(parent X Y)\n");
  * search.execute((rule) => {
  *   console.log(rule.toString());
  *   return true; // Continue search

From d99197a5461cf8959ed8cdccaeb95b2dc347e256 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 24 Nov 2025 04:04:46 +0000
Subject: [PATCH 05/11] Add concrete examples to ground() method documentation

Co-authored-by: hzhangxyz <11623447+hzhangxyz@users.noreply.github.com>
---
 tsds/tsds.mts | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/tsds/tsds.mts b/tsds/tsds.mts
index 267b51a..7d5ee96 100644
--- a/tsds/tsds.mts
+++ b/tsds/tsds.mts
@@ -332,6 +332,7 @@ export class term_t extends _common_t<dst.Term> {
      * Ground this term using a dictionary to substitute variables with values.
      *
      * @param other - A term representing a dictionary (list of pairs). Each pair contains a variable and its substitution value.
+     *                Example: "((`a b))" means substitute variable `a with value b.
      * @param scope - Optional scope string for variable scoping.
      * @returns The grounded term, or null if grounding fails.
      */
@@ -347,13 +348,13 @@ export class term_t extends _common_t<dst.Term> {
 
 /**
  * Wrapper class for logical rules in the deductive system.
- * A rule consists of a conclusion and zero or more premises.
+ * A rule consists of zero or more premises (above the line) and a conclusion (below the line).
  *
  * @example
  * ```typescript
  * const rule = new rule_t("(father X Y)\n----------\n(parent X Y)\n");
  * console.log(rule.conclusion().toString()); // "(parent X Y)"
- * console.log(rule.length()); // Number of premises
+ * console.log(rule.length()); // 1 (number of premises)
  * ```
  */
 export class rule_t extends _common_t<dst.Rule> {
@@ -400,6 +401,7 @@ export class rule_t extends _common_t<dst.Rule> {
      * Ground this rule using a dictionary to substitute variables with values.
      *
      * @param other - A rule representing a dictionary (list of pairs). Each pair contains a variable and its substitution value.
+     *                Example: new rule_t("((`a b))") means substitute variable `a with value b.
      * @param scope - Optional scope string for variable scoping.
      * @returns The grounded rule, or null if grounding fails.
      */

From 41a08a90879aeda1164403574b0502a0758a4c03 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 24 Nov 2025 04:25:21 +0000
Subject: [PATCH 06/11] Fix variable examples to use backtick prefix

Co-authored-by: hzhangxyz <11623447+hzhangxyz@users.noreply.github.com>
---
 tsds/tsds.mts | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/tsds/tsds.mts b/tsds/tsds.mts
index 7d5ee96..f6b508e 100644
--- a/tsds/tsds.mts
+++ b/tsds/tsds.mts
@@ -186,8 +186,8 @@ export class string_t extends _common_t<dst.String> {
  *
  * @example
  * ```typescript
- * const var1 = new variable_t("X");
- * console.log(var1.name().toString()); // "X"
+ * const var1 = new variable_t("`X");
+ * console.log(var1.name().toString()); // "`X"
  * ```
  */
 export class variable_t extends _common_t<dst.Variable> {
@@ -293,7 +293,7 @@ export class list_t extends _common_t<dst.List> {
  *
  * @example
  * ```typescript
- * const term = new term_t("(f X a)");
+ * const term = new term_t("(f `x a)");
  * const innerTerm = term.term(); // Get the underlying term type
  * ```
  */
@@ -352,8 +352,8 @@ export class term_t extends _common_t<dst.Term> {
  *
  * @example
  * ```typescript
- * const rule = new rule_t("(father X Y)\n----------\n(parent X Y)\n");
- * console.log(rule.conclusion().toString()); // "(parent X Y)"
+ * const rule = new rule_t("(father `X `Y)\n----------\n(parent `X `Y)\n");
+ * console.log(rule.conclusion().toString()); // "(parent `X `Y)"
  * console.log(rule.length()); // 1 (number of premises)
  * ```
  */
@@ -439,7 +439,7 @@ export class rule_t extends _common_t<dst.Rule> {
  * ```typescript
  * const search = new search_t();
  * search.add("(parent john mary)");
- * search.add("(father X Y)\n----------\n(parent X Y)\n");
+ * search.add("(father `X `Y)\n----------\n(parent `X `Y)\n");
  * search.execute((rule) => {
  *   console.log(rule.toString());
  *   return true; // Continue search

From 180464810c85fba8f0026ec4801904888c2078b1 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 24 Nov 2025 05:28:30 +0000
Subject: [PATCH 07/11] Fix variable_t example comment to match actual output

Co-authored-by: hzhangxyz <11623447+hzhangxyz@users.noreply.github.com>
---
 tsds/tsds.mts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tsds/tsds.mts b/tsds/tsds.mts
index f6b508e..46c18db 100644
--- a/tsds/tsds.mts
+++ b/tsds/tsds.mts
@@ -187,7 +187,7 @@ export class string_t extends _common_t<dst.String> {
  * @example
  * ```typescript
  * const var1 = new variable_t("`X");
- * console.log(var1.name().toString()); // "`X"
+ * console.log(var1.name().toString()); // "X"
  * ```
  */
 export class variable_t extends _common_t<dst.Variable> {

From ebd4b9df914258a2c7c2171c97e305d7233d4c54 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 24 Nov 2025 05:51:31 +0000
Subject: [PATCH 08/11] Add examples for ground() and match() methods and fix
 search callback comment

Co-authored-by: hzhangxyz <11623447+hzhangxyz@users.noreply.github.com>
---
 tsds/tsds.mts | 33 ++++++++++++++++++++++++++++++++-
 1 file changed, 32 insertions(+), 1 deletion(-)

diff --git a/tsds/tsds.mts b/tsds/tsds.mts
index 46c18db..0431766 100644
--- a/tsds/tsds.mts
+++ b/tsds/tsds.mts
@@ -335,6 +335,18 @@ export class term_t extends _common_t<dst.Term> {
      *                Example: "((`a b))" means substitute variable `a with value b.
      * @param scope - Optional scope string for variable scoping.
      * @returns The grounded term, or null if grounding fails.
+     *
+     * @example
+     * ```typescript
+     * const a = new term_t("`a");
+     * const b = new term_t("((`a b))");
+     * console.log(a.ground(b).toString()); // "b"
+     *
+     * // With scope
+     * const c = new term_t("`a");
+     * const d = new term_t("((x y `a `b) (y x `b `c))");
+     * console.log(c.ground(d, "x").toString()); // "`c"
+     * ```
      */
     ground(other: term_t, scope: string = ""): term_t | null {
         const capacity = buffer_size();
@@ -404,6 +416,18 @@ export class rule_t extends _common_t<dst.Rule> {
      *                Example: new rule_t("((`a b))") means substitute variable `a with value b.
      * @param scope - Optional scope string for variable scoping.
      * @returns The grounded rule, or null if grounding fails.
+     *
+     * @example
+     * ```typescript
+     * const a = new rule_t("`a");
+     * const b = new rule_t("((`a b))");
+     * console.log(a.ground(b).toString()); // "----\nb\n"
+     *
+     * // With scope
+     * const c = new rule_t("`a");
+     * const d = new rule_t("((x y `a `b) (y x `b `c))");
+     * console.log(c.ground(d, "x").toString()); // "----\n`c\n"
+     * ```
      */
     ground(other: rule_t, scope: string = ""): rule_t | null {
         const capacity = buffer_size();
@@ -420,6 +444,13 @@ export class rule_t extends _common_t<dst.Rule> {
      *
      * @param other - The rule to match against.
      * @returns The matched rule, or null if matching fails.
+     *
+     * @example
+     * ```typescript
+     * const mp = new rule_t("(`p -> `q)\n`p\n`q\n");
+     * const pq = new rule_t("((! (! `x)) -> `x)");
+     * console.log(mp.match(pq).toString()); // "(! (! `x))\n----------\n`x\n"
+     * ```
      */
     match(other: rule_t): rule_t | null {
         const capacity = buffer_size();
@@ -442,7 +473,7 @@ export class rule_t extends _common_t<dst.Rule> {
  * search.add("(father `X `Y)\n----------\n(parent `X `Y)\n");
  * search.execute((rule) => {
  *   console.log(rule.toString());
- *   return true; // Continue search
+ *   return false; // Return false to continue, true to stop
  * });
  * ```
  */

From 5cfd90afabd57c2ff9e9396758522f0e0dc02724 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 24 Nov 2025 06:18:33 +0000
Subject: [PATCH 09/11] Fix search_t documentation per reviewer feedback

Co-authored-by: hzhangxyz <11623447+hzhangxyz@users.noreply.github.com>
---
 tsds/tsds.mts | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/tsds/tsds.mts b/tsds/tsds.mts
index 0431766..b9e73d3 100644
--- a/tsds/tsds.mts
+++ b/tsds/tsds.mts
@@ -483,17 +483,17 @@ export class search_t {
     /**
      * Creates a new search engine instance.
      *
-     * @param limit_size - Maximum number of rules/facts in the knowledge base (default: 1000).
-     * @param buffer_size - Buffer size for internal operations (default: 10000).
+     * @param limit_size - Size of the buffer for storing the final objects (rules/facts) in the knowledge base (default: 1000).
+     * @param buffer_size - Size of the buffer for internal operations like conversions and transformations (default: 10000).
      */
     constructor(limit_size: number = 1000, buffer_size: number = 10000) {
         this._search = new ds.Search(limit_size, buffer_size);
     }
 
     /**
-     * Set the maximum number of rules/facts the search engine can hold.
+     * Set the size of the buffer for storing final objects.
      *
-     * @param limit_size - The new limit size.
+     * @param limit_size - The new limit size for storing rules/facts.
      */
     set_limit_size(limit_size: number): void {
         this._search.set_limit_size(limit_size);
@@ -528,7 +528,7 @@ export class search_t {
     /**
      * Execute the search engine with a callback for each inferred rule.
      *
-     * @param callback - Function called for each candidate rule. Return true to continue, false to stop.
+     * @param callback - Function called for each candidate rule. Return false to continue, true to stop.
      * @returns The number of rules processed.
      */
     execute(callback: (candidate: rule_t) => boolean): number {

From d722829efbe0bec626aee1f67077219751358849 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 24 Nov 2025 06:28:18 +0000
Subject: [PATCH 10/11] Fix consistency in constructor size parameter
 descriptions

Co-authored-by: hzhangxyz <11623447+hzhangxyz@users.noreply.github.com>
---
 tsds/tsds.mts | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/tsds/tsds.mts b/tsds/tsds.mts
index b9e73d3..47b9f76 100644
--- a/tsds/tsds.mts
+++ b/tsds/tsds.mts
@@ -73,7 +73,7 @@ class _common_t<T extends Common> {
      * @param type - The static type interface for this common type.
      * @param value - Initial value (can be another instance, base value, string, or buffer).
      * @param size - Optional buffer capacity for the internal storage.
-     * @throws {Error} If initialization fails or invalid arguments provided.
+     * @throws {Error} If initialization fails or invalid arguments are provided.
      */
     constructor(type: StaticCommon<T>, value: InitialArgument<T>, size: number = 0) {
         this.type = type;
@@ -172,7 +172,7 @@ export class string_t extends _common_t<dst.String> {
      * Creates a new string instance.
      *
      * @param value - Initial value (string, buffer, or another string_t).
-     * @param size - Optional buffer size for string initialization.
+     * @param size - Optional buffer capacity for the internal storage.
      * @throws {Error} If initialization fails.
      */
     constructor(value: InitialArgument<dst.String>, size: number = 0) {
@@ -195,7 +195,7 @@ export class variable_t extends _common_t<dst.Variable> {
      * Creates a new variable instance.
      *
      * @param value - Initial value (string, buffer, or another variable_t).
-     * @param size - Optional buffer size for string initialization.
+     * @param size - Optional buffer capacity for the internal storage.
      * @throws {Error} If initialization fails.
      */
     constructor(value: InitialArgument<dst.Variable>, size: number = 0) {
@@ -227,7 +227,7 @@ export class item_t extends _common_t<dst.Item> {
      * Creates a new item instance.
      *
      * @param value - Initial value (string, buffer, or another item_t).
-     * @param size - Optional buffer size for string initialization.
+     * @param size - Optional buffer capacity for the internal storage.
      * @throws {Error} If initialization fails.
      */
     constructor(value: InitialArgument<dst.Item>, size: number = 0) {
@@ -260,7 +260,7 @@ export class list_t extends _common_t<dst.List> {
      * Creates a new list instance.
      *
      * @param value - Initial value (string, buffer, or another list_t).
-     * @param size - Optional buffer size for string initialization.
+     * @param size - Optional buffer capacity for the internal storage.
      * @throws {Error} If initialization fails.
      */
     constructor(value: InitialArgument<dst.List>, size: number = 0) {
@@ -302,7 +302,7 @@ export class term_t extends _common_t<dst.Term> {
      * Creates a new term instance.
      *
      * @param value - Initial value (string, buffer, or another term_t).
-     * @param size - Optional buffer size for string initialization.
+     * @param size - Optional buffer capacity for the internal storage.
      * @throws {Error} If initialization fails.
      */
     constructor(value: InitialArgument<dst.Term>, size: number = 0) {
@@ -374,7 +374,7 @@ export class rule_t extends _common_t<dst.Rule> {
      * Creates a new rule instance.
      *
      * @param value - Initial value (string, buffer, or another rule_t).
-     * @param size - Optional buffer size for string initialization.
+     * @param size - Optional buffer capacity for the internal storage.
      * @throws {Error} If initialization fails.
      */
     constructor(value: InitialArgument<dst.Rule>, size: number = 0) {

From e984d2423dcdb57e75767dcb72ae551f6b0d88ef Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 24 Nov 2025 06:37:57 +0000
Subject: [PATCH 11/11] Fix remaining documentation issues per reviewer
 feedback

Co-authored-by: hzhangxyz <11623447+hzhangxyz@users.noreply.github.com>
---
 tsds/tsds.mts | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/tsds/tsds.mts b/tsds/tsds.mts
index 47b9f76..8a3e690 100644
--- a/tsds/tsds.mts
+++ b/tsds/tsds.mts
@@ -12,7 +12,7 @@ let _buffer_size: number = 1024;
 
 /**
  * Gets the current buffer size, or sets a new buffer size and returns the previous value.
- * The buffer size is used for string conversions and internal storage of terms, rules, and other objects.
+ * The buffer size is used for internal operations like conversions and transformations.
  *
  * @param size - The new buffer size to set. If 0 (default), the current size is returned without modification.
  * @returns The previous buffer size value.
@@ -401,7 +401,7 @@ export class rule_t extends _common_t<dst.Rule> {
     }
 
     /**
-     * Get the conclusion (head) of the rule.
+     * Get the conclusion of the rule.
      *
      * @returns The conclusion term.
      */
@@ -440,9 +440,10 @@ export class rule_t extends _common_t<dst.Rule> {
 
     /**
      * Match this rule with another rule using unification.
-     * This performs pattern matching and unification between the two rules.
+     * This unifies the first premise of this rule with the other rule.
+     * The other rule must be a fact (a rule without premises).
      *
-     * @param other - The rule to match against.
+     * @param other - The rule to match against (must be a fact without premises).
      * @returns The matched rule, or null if matching fails.
      *
      * @example