datalog: dl-magic-query driver (204/204)

End-to-end magic-sets entry point. Given (db, query-goal):
  - copies the caller's EDB facts (relations not headed by any
    rule) into a fresh internal db
  - adds the magic seed fact
  - adds the rewritten rules
  - saturates and runs the query
  - returns the substitution list

Caller's db is untouched. Equivalent to dl-query for any
fully-stratifiable program; intended as a perf alternative on
goal-shaped queries against large recursive relations.

2 new tests: equivalence to dl-query on chain-3 ancestor, and
non-mutation of the caller's db (rules count unchanged).

lib/datalog/magic.sx

@@ -341,3 +341,63 @@
            query-rel
            query-adornment
            query-args)}))))
+
+;; ── Top-level magic-sets driver ─────────────────────────────────
+;;
+;; (dl-magic-query db query-goal) — run `query-goal` under magic-sets
+;; evaluation. Builds a fresh internal db with:
+;;   - the caller's EDB facts (relations not headed by any rule),
+;;   - the magic seed fact, and
+;;   - the rewritten rules.
+;; Saturates and queries, returning the substitution list. The
+;; caller's db is untouched.
+;;
+;; Useful primarily as a perf alternative for queries that only
+;; need a small slice of a recursive relation. Equivalent to
+;; dl-query for any single fully-stratifiable program.
+
+(define
+  dl-magic-rule-heads
+  (fn
+    (rules)
+    (let ((seen (list)))
+      (do
+        (for-each
+          (fn
+            (r)
+            (let ((h (dl-rel-name (get r :head))))
+              (when
+                (and (not (nil? h)) (not (dl-member-string? h seen)))
+                (append! seen h))))
+          rules)
+        seen))))
+
+(define
+  dl-magic-query
+  (fn
+    (db query-goal)
+    (let
+      ((query-rel (dl-rel-name query-goal))
+        (query-adn (dl-adorn-goal query-goal)))
+      (let
+        ((query-args (dl-bound-args query-goal query-adn))
+          (rules (dl-rules db)))
+        (let
+          ((rewritten (dl-magic-rewrite rules query-rel query-adn query-args))
+            (mdb (dl-make-db))
+            (rule-heads (dl-magic-rule-heads rules)))
+          (do
+            ;; Copy EDB facts (relations not headed by any caller rule).
+            (for-each
+              (fn
+                (rel)
+                (when
+                  (not (dl-member-string? rel rule-heads))
+                  (for-each
+                    (fn (t) (dl-add-fact! mdb t))
+                    (dl-rel-tuples db rel))))
+              (keys (get db :facts)))
+            ;; Seed + rewritten rules.
+            (dl-add-fact! mdb (get rewritten :seed))
+            (for-each (fn (r) (dl-add-rule! mdb r)) (get rewritten :rules))
+            (dl-query mdb query-goal)))))))

lib/datalog/scoreboard.json

@@ -1,8 +1,8 @@
 {
   "lang": "datalog",
-  "total_passed": 202,
+  "total_passed": 204,
   "total_failed": 0,
-  "total": 202,
+  "total": 204,
   "suites": [
     {"name":"tokenize","passed":26,"failed":0,"total":26},
     {"name":"parse","passed":18,"failed":0,"total":18},
@@ -13,8 +13,8 @@
     {"name":"negation","passed":10,"failed":0,"total":10},
     {"name":"aggregates","passed":18,"failed":0,"total":18},
     {"name":"api","passed":14,"failed":0,"total":14},
-    {"name":"magic","passed":18,"failed":0,"total":18},
+    {"name":"magic","passed":20,"failed":0,"total":20},
     {"name":"demo","passed":18,"failed":0,"total":18}
   ],
-  "generated": "2026-05-08T09:58:16+00:00"
+  "generated": "2026-05-08T10:00:29+00:00"
 }

lib/datalog/scoreboard.md

@@ -1,6 +1,6 @@
 # datalog scoreboard
 
-**202 / 202 passing** (0 failure(s)).
+**204 / 204 passing** (0 failure(s)).
 
 | Suite | Passed | Total | Status |
 |-------|--------|-------|--------|
@@ -13,5 +13,5 @@
 | negation | 10 | 10 | ok |
 | aggregates | 18 | 18 | ok |
 | api | 14 | 14 | ok |
-| magic | 18 | 18 | ok |
+| magic | 20 | 20 | ok |
 | demo | 18 | 18 | ok |

lib/datalog/tests/magic.sx

@@ -196,6 +196,34 @@
               (len (dl-relation db "ancestor")))))
         6)
 
+      ;; dl-magic-query: end-to-end driver, doesn't mutate caller's db.
+      (dl-mt-test! "magic-query equivalent to dl-query"
+        (let
+          ((db (dl-program
+                 "parent(a, b). parent(b, c). parent(c, d).
+                  ancestor(X, Y) :- parent(X, Y).
+                  ancestor(X, Z) :- parent(X, Y), ancestor(Y, Z).")))
+          (let
+            ((semi (dl-query db (list (quote ancestor) (quote a) (quote X))))
+              (magic (dl-magic-query
+                       db (list (quote ancestor) (quote a) (quote X)))))
+            (= (len semi) (len magic))))
+        true)
+
+      ;; magic-query doesn't mutate caller db.
+      (dl-mt-test! "magic-query preserves caller db"
+        (let
+          ((db (dl-program
+                 "parent(a, b). parent(b, c).
+                  ancestor(X, Y) :- parent(X, Y).
+                  ancestor(X, Z) :- parent(X, Y), ancestor(Y, Z).")))
+          (let
+            ((rules-before (len (dl-rules db))))
+            (do
+              (dl-magic-query db (list (quote ancestor) (quote a) (quote X)))
+              (= rules-before (len (dl-rules db))))))
+        true)
+
       (dl-mt-test! "magic-rewritten finds same answers"
         (let
           ((rules