--- a/doc/design.txt	Sun Nov 05 11:38:18 2023 -0500
+++ b/doc/design.txt	Sun Aug 17 16:12:25 2025 -0400
@@ -8,7 +8,9 @@
 Roundup - An Issue-Tracking System for Knowledge Workers
 ========================================================
 
-:Authors: Ka-Ping Yee (original), Richard Jones (implementation)
+:Authors: Ka-Ping Yee (original_), Richard Jones (implementation)
+
+.. _original: spec.html
 
 Contents
 
@@ -1522,6 +1524,7 @@
             - klass (optional)
             - properties (optional)
             - check function (optional)
+            - filter function (optional)
 
             The klass may be unset, indicating that this permission is
             not locked to a particular hyperdb class. There may be
@@ -1534,6 +1537,16 @@
             If check function is set, permission is granted only when
             the function returns value interpreted as boolean true.
             The function is called with arguments db, userid, itemid.
+
+            A filter function complements a check function: It is used
+            when searching for viewable items. The filter function
+            allows to filter in SQL rather than calling the check
+            function for each item after a query. It must return a list
+            of dictionaries containing parameters for the hyperdb.Class.filter
+            method. An empty list indicates no access. The signature of
+            the filter function is::
+
+                def filter(db, userid, klass):
         '''
 
     class Role: