;; lib/datalog/datalog.sx — public API documentation index.
;;
;; This file is reference-only — `load` is an epoch-protocol command,
;; not an SX function, so it cannot reload a list of files from inside
;; another `.sx` file. To set up a fresh sx_server session with all
;; modules in scope, issue these loads in order:
;;
;;   (load "lib/datalog/tokenizer.sx")
;;   (load "lib/datalog/parser.sx")
;;   (load "lib/datalog/unify.sx")
;;   (load "lib/datalog/db.sx")
;;   (load "lib/datalog/builtins.sx")
;;   (load "lib/datalog/aggregates.sx")
;;   (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.)
;;
;; ── Public API surface ─────────────────────────────────────────────
;;
;;   Source / data:
;;     (dl-tokenize "src")              → token list
;;     (dl-parse "src")                 → parsed clauses
;;     (dl-program "src")               → db built from a source string
;;     (dl-program-data facts rules)    → db from SX data lists; rules
;;                                        accept either dict form or
;;                                        list form with `<-` arrow
;;
;;   Construction (mutates db):
;;     (dl-make-db)                     empty db
;;     (dl-add-fact! db lit)            rejects non-ground
;;     (dl-add-rule! db rule)           rejects unsafe rules
;;     (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
;;     (dl-saturate-naive! db)          reference (slow on chains)
;;     (dl-saturate-rules! db rules)    per-rule-set semi-naive worker
;;     (dl-query db goal)               list of substitution dicts
;;     (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 ─────────────────────────────────────────────
;;
;;   Positive             (rel arg ... arg)
;;   Negation             {:neg (rel arg ...)}
;;   Comparison           (< X Y), (<= X Y), (> X Y), (>= X Y),
;;                        (= X Y), (!= X Y)
;;   Arithmetic           (is Z (+ X Y)) and (- * /)
;;   Aggregation          (count R V Goal),  (sum R V Goal),
;;                        (min R V Goal),    (max R V Goal),
;;                        (findall L V Goal)
;;
;; ── Variable conventions ───────────────────────────────────────────
;;
;;   Variables: SX symbols whose first char is uppercase A–Z or '_'.
;;   Anonymous '_' is renamed to a fresh _anon<N> per occurrence at
;;   rule/query load time so multiple '_' don't unify.
;;
;; ── Demo programs ──────────────────────────────────────────────────
;;
;;   See lib/datalog/demo.sx — federation, content, permissions, and
;;   the canonical "cooking posts by people I follow (transitively)"
;;   example.
;;
;; ── Status ─────────────────────────────────────────────────────────
;;
;;   See plans/datalog-on-sx.md — phase-by-phase progress log and
;;   roadmap. Run `bash lib/datalog/conformance.sh` to refresh
;;   `lib/datalog/scoreboard.{json,md}`.