From ce8fed6b224f6efb6902fd4be9fe262159075e65 Mon Sep 17 00:00:00 2001
From: giles <giles.bradshaw@rose-ash.com>
Date: Fri, 8 May 2026 10:08:58 +0000
Subject: [PATCH] datalog: refresh datalog.sx API doc with magic-sets + later
 additions

---
 lib/datalog/datalog.sx | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/lib/datalog/datalog.sx b/lib/datalog/datalog.sx
index 8189ec09..54e2ce7d 100644
--- a/lib/datalog/datalog.sx
+++ b/lib/datalog/datalog.sx
@@ -14,6 +14,7 @@
 ;;   (load "lib/datalog/strata.sx")
 ;;   (load "lib/datalog/eval.sx")
 ;;   (load "lib/datalog/api.sx")
+;;   (load "lib/datalog/magic.sx")
 ;;   (load "lib/datalog/demo.sx")
 ;;
 ;; (lib/datalog/conformance.sh runs this load list automatically.)
@@ -35,10 +36,15 @@
 ;;     (dl-rule head body)              dict-rule constructor
 ;;     (dl-add-clause! db clause)       parser output → fact or rule
 ;;     (dl-load-program! db src)        string source
+;;     (dl-set-strategy! db strategy)   :semi-naive default; :magic
+;;                                        is informational, use
+;;                                        dl-magic-query for actual
+;;                                        magic-sets evaluation
 ;;
 ;;   Mutation:
 ;;     (dl-assert! db lit)              add + re-saturate
 ;;     (dl-retract! db lit)             drop EDB, wipe IDB, re-saturate
+;;     (dl-clear-idb! db)               wipe rule-headed relations
 ;;
 ;;   Query / inspection:
 ;;     (dl-saturate! db)                stratified semi-naive default
@@ -48,6 +54,18 @@
 ;;     (dl-relation db rel-name)        tuple list for a relation
 ;;     (dl-rules db)                    rule list
 ;;     (dl-fact-count db)               total ground tuples
+;;     (dl-summary db)                  {<rel>: count} for inspection
+;;
+;;   Single-call convenience:
+;;     (dl-eval source query-source)         parse, run, return substs
+;;     (dl-eval-magic source query-source)   single-goal → magic-sets
+;;
+;;   Magic-sets (lib/datalog/magic.sx):
+;;     (dl-adorn-goal goal)             "b/f" adornment string
+;;     (dl-rule-sips rule head-adn)     SIPS analysis per body lit
+;;     (dl-magic-rewrite rules rel adn args)
+;;                                       rewritten rule list + seed
+;;     (dl-magic-query db query-goal)    end-to-end magic-sets query
 ;;
 ;; ── Body literal kinds ─────────────────────────────────────────────
 ;;