tiny-datalog 0.5.0__tar.gz → 0.7.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (25) hide show
  1. {tiny_datalog-0.5.0/tiny_datalog.egg-info → tiny_datalog-0.7.0}/PKG-INFO +80 -37
  2. {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/README.md +79 -36
  3. {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/pyproject.toml +2 -1
  4. {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/tiny_datalog/__init__.py +4 -2
  5. {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/tiny_datalog/chase.py +5 -1
  6. {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/tiny_datalog/containment.py +11 -1
  7. {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/tiny_datalog/core.py +291 -20
  8. {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/tiny_datalog/datalog.py +163 -38
  9. {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/tiny_datalog/engines.py +40 -7
  10. {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/tiny_datalog/incremental.py +18 -7
  11. {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/tiny_datalog/magic.py +19 -1
  12. {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/tiny_datalog/prolog.py +4 -1
  13. {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/tiny_datalog/semantics.py +6 -3
  14. {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/tiny_datalog/semiring.py +10 -3
  15. tiny_datalog-0.7.0/tiny_datalog/slg.py +553 -0
  16. {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/tiny_datalog/tabling.py +144 -45
  17. {tiny_datalog-0.5.0 → tiny_datalog-0.7.0/tiny_datalog.egg-info}/PKG-INFO +80 -37
  18. {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/tiny_datalog.egg-info/SOURCES.txt +1 -0
  19. {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/tiny_datalog.egg-info/entry_points.txt +1 -0
  20. {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/LICENSE +0 -0
  21. {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/setup.cfg +0 -0
  22. {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/tiny_datalog/defeasible.py +0 -0
  23. {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/tiny_datalog/subsumption.py +0 -0
  24. {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/tiny_datalog.egg-info/dependency_links.txt +0 -0
  25. {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/tiny_datalog.egg-info/top_level.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: tiny-datalog
3
- Version: 0.5.0
3
+ Version: 0.7.0
4
4
  Summary: A Datalog engine whose core you can read in an afternoon, and a course built on it
5
5
  Author: Andrew Goodchild
6
6
  License-Expression: MIT
@@ -127,7 +127,7 @@ Nothing to install:
127
127
 
128
128
  ```sh
129
129
  git clone https://github.com/andrewgoodchild/tiny-datalog && cd tiny-datalog
130
- python3 tests.py # 326 tests, ~12s
130
+ python3 tests.py # 402 tests, ~20s
131
131
  ```
132
132
 
133
133
  ## Why the language choice decides what you can ask later
@@ -183,7 +183,9 @@ it:
183
183
 
184
184
  Every feature in this repository is a check of that kind: stratification
185
185
  catches circularity, `--models` catches contradiction and ambiguity,
186
- `containment.py` catches redundancy, and `--explain` produces the
186
+ `containment.py` catches redundancy, integrity constraints catch a rule
187
+ set that breaks the policy stated another way, warnings catch the typo
188
+ that silently empties a relation, and `--explain` produces the
187
189
  derivation somebody has to sign off on.
188
190
 
189
191
  Two limits. An engine checks coherence, not intent: a rule set can pass
@@ -194,7 +196,7 @@ the better tool, and that covers most problems.
194
196
 
195
197
  ## What else you can ask it
196
198
 
197
- The worked example above is one row of a table. The full version — 23
199
+ The worked example above is one row of a table. The full version — 32
198
200
  questions, each with the command that answers it and the lesson that
199
201
  builds the machinery — is in
200
202
  [getting started](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/getting-started.md), beside the reading
@@ -227,20 +229,29 @@ is the whole relation the guards are pure overhead.
227
229
  [Lesson 7](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/07-magic-sets.md) works through why.
228
230
 
229
231
  Correctness is checked by a seeded differential fuzzer that generates
230
- stratified programs and demands semi-naive, naive, magic-sets and
231
- tabled evaluation all agree, and that incremental maintenance matches
232
- recomputation under random updates. 400 programs per run;
232
+ stratified programs, aggregates included, and demands that all five
233
+ engines agree; that SLG matches the well-founded model on unstratified
234
+ ones, with and without subsumptive tabling; and that incremental
235
+ maintenance matches recomputation under random updates. 400 programs
236
+ per run;
233
237
  `TINY_DATALOG_FUZZ=3000 python3 tests.py DifferentialFuzzTests` soaks.
234
238
 
235
239
  Answers are also checked against engines this repository did not write.
236
240
  [`conformance/`](https://github.com/andrewgoodchild/tiny-datalog/tree/main/conformance)
237
241
  runs the [datalog-conformance](https://pypi.org/project/datalog-conformance/)
238
- corpus, harvested from Soufflé, Nemo and Crepe, through all four
242
+ corpus, harvested from Soufflé, Nemo and Crepe, through all five
239
243
  strategies, and its defeasible theories, from SPINdle and the papers,
240
244
  through `defeasible.py`: 195 cases pass. Every skip is named with its
241
245
  reason: arithmetic and 10⁵-fact joins, which this course omits on
242
246
  purpose, or cases written for a different logic.
243
247
 
248
+ And the tests themselves are checked: `benchmarks/mutate.py` makes
249
+ each one-line break a bug could make (a `<` for a `<=`, a dropped
250
+ `not`, a deleted statement) and runs the suite against each. At 0.7.0
251
+ the suite caught 91% of 3,322 such mutants. Most of the rest change
252
+ nothing a user could observe, such as a counter's starting value or a
253
+ default limit raised by one; the others are mainly CLI printing.
254
+
244
255
  ## Learning Datalog
245
256
 
246
257
  `lessons/` is a complete course, no prior exposure assumed, every
@@ -250,10 +261,12 @@ observe that the literature advises people building Datalog engines
250
261
  better than people trying to *use* one; this course does both halves
251
262
  on purpose — sixteen lessons where the engine is the explanation, then
252
263
  a lesson on authoring rules that survive review, one on a logic
253
- built for rules with exceptions, and three where the engine goes to
264
+ built for rules with exceptions, and five where the engine goes to
254
265
  work: [authorization](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/20-authorization.md),
255
266
  [program analysis](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/21-program-analysis.md),
256
- and [knowledge graphs and the chase](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/22-knowledge-graphs.md).
267
+ [knowledge graphs and the chase](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/22-knowledge-graphs.md),
268
+ [time and history](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/23-time.md),
269
+ and [memory for a language-model agent](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/24-memory.md).
257
270
  And it is built to be
258
271
  inherited: `git clone`, no dependencies, no hosted anything, and every
259
272
  quoted transcript re-verified by CI — the exercises cannot rot. (For where each
@@ -301,10 +314,9 @@ see [pyDatalog](https://pypi.org/project/pyDatalog/).
301
314
  Deliberate omissions, because saying why teaches more than lacking them
302
315
  quietly:
303
316
 
304
- - **Arithmetic and comparisons.** A built-in isn't a relation you can
305
- enumerate, so it must be *evaluated* the moment its operands bind —
306
- which entangles correctness with join order and forces terms to
307
- become trees. [Lesson 14](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/14-arithmetic.md) is the whole
317
+ - **Arithmetic.** `Z = X + 1` makes values nobody stated, so it can make
318
+ a relation infinite, and the termination theorem goes with it.
319
+ [Lesson 14](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/14-arithmetic.md) is the whole
308
320
  story, including what to do instead.
309
321
  - **Indexes and join planning.** Every join is a nested loop so the
310
322
  algorithms stay one-screen readable. It is also why the magic-sets
@@ -317,7 +329,10 @@ quietly:
317
329
 
318
330
  Aggregation used to be on this list;
319
331
  [lesson 13](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/13-aggregation.md) is what promoting an omission
320
- into a feature looks like.
332
+ into a feature looks like. Comparisons (`<`, `<=`, `>`, `>=`, `=`,
333
+ `!=`) used to share arithmetic's entry. They check values and never
334
+ make them, so they can only filter, and lesson 14's own argument lets
335
+ them in; [lesson 23](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/23-time.md) puts them to work.
321
336
 
322
337
  ## Using it in your own project
323
338
 
@@ -354,8 +369,27 @@ engine = run_program(rules, facts={
354
369
  engine.query("exposed(S, C)") # [{'S': 'app', 'C': 'cve_2026_0001'}]
355
370
  ```
356
371
 
372
+ A rule with no head is an integrity constraint, a situation that must
373
+ never arise. `engine.violations()` lists each broken one with its
374
+ counterexamples, and the command line prints them and exits with
375
+ status 3:
376
+
377
+ ```python
378
+ checked = run_program(rules + ":- exposed(S, C).", facts={
379
+ "depends": [("app", "lib"), ("lib", "core")],
380
+ "service": ["app"],
381
+ "vulnerable": [("core", "cve_2026_0001")],
382
+ })
383
+ checked.violations() # [(constraint, [{'S': 'app', 'C': 'cve_2026_0001'}])]
384
+ ```
385
+
386
+ For agents, `skills/tiny-datalog/SKILL.md` is an Agent Skill that
387
+ teaches a coding agent the language and the habits (explain before
388
+ trusting, state properties as constraints); copy it into your agent's
389
+ skills directory.
390
+
357
391
  The command-line interface installs too, as `tiny-datalog` (and
358
- `tiny-datalog-semiring`, `-tabling`, `-incremental`, `-subsumption`,
392
+ `tiny-datalog-semiring`, `-tabling`, `-slg`, `-incremental`, `-subsumption`,
359
393
  `-containment`, `-defeasible`, `-prolog` for the other engines and the
360
394
  extensions):
361
395
 
@@ -371,16 +405,20 @@ installed package; clone the repository for that.
371
405
  ```
372
406
  tiny_datalog/ the code you read, in three tiers:
373
407
  core.py the common core — the language every module shares:
374
- AST, parser, safety checks, stratification, matching,
375
- formatting, query helpers
376
- engines — four strategies, one answer (engines.py lists them):
408
+ AST, parser, safety checks, comparisons, stratification,
409
+ matching, formatting, query helpers, warnings
410
+ engines — five strategies, one answer (engines.py lists them):
377
411
  datalog.py the base engine: semi-naive and naive bottom-up
378
- evaluation, aggregation, --explain / why-not, the CLI
412
+ evaluation, aggregation, integrity constraints,
413
+ --explain / why-not, --assume, the CLI
379
414
  magic.py the magic-sets rewriting (a program-to-program pass)
380
415
  tabling.py tabled top-down evaluation (iterative QSQR)
381
- engines.py the registry and the interface the four share
416
+ engines.py the registry and the interface the five share (the
417
+ fifth is SLG, from slg.py below, held to stratified
418
+ programs)
382
419
  extensions — other questions asked of the same programs:
383
420
  semantics.py grounding, stable models, the well-founded model
421
+ slg.py SLG resolution: the well-founded model, top-down
384
422
  semiring.py semiring-valued evaluation (costs, counts, provenance,
385
423
  probabilities)
386
424
  incremental.py insertions + DRed deletions over a live materialisation
@@ -392,16 +430,19 @@ tiny_datalog/ the code you read, in three tiers:
392
430
  acyclicity
393
431
  *.py three-line launchers, so `python3 datalog.py ...` works
394
432
  straight from a checkout with nothing installed
395
- programs/ teaching programs, numbered by the lesson that uses
396
- them (00-* are the README's examples)
397
- lessons/ getting started, glossary, and lessons 0–22
433
+ programs/ teaching programs, named for what they model; each
434
+ lesson says which ones it runs
435
+ lessons/ getting started, glossary, and lessons 0–24
398
436
  exercises/ worked answers, verified by the test suite
399
437
  cases/ golden test cases — add one without writing Python
438
+ skills/ an Agent Skill that teaches coding agents to use the engine
400
439
  conformance/ the external datalog-conformance corpus (Soufflé, Nemo,
401
440
  Crepe, SPINdle), run against every evaluation strategy
402
441
  benchmarks/ scaled input generators (chain/tree/clique/grid, an EL
403
- ontology, and the N-queens puzzle)
404
- tests.py 326 tests: every shipped program and exercise answer is
442
+ ontology, and the N-queens puzzle), and mutate.py,
443
+ which breaks the code one line at a time to measure
444
+ how much of it the tests would notice (91% at 0.7.0)
445
+ tests.py 402 tests: every shipped program and exercise answer is
405
446
  executed, a conformance suite runs every query through
406
447
  every engine that handles it, and a seeded fuzzer checks
407
448
  the same property on random programs
@@ -417,7 +458,7 @@ used.
417
458
  This project started as an attempt at a tiny implementation of
418
459
  Datalog, small enough to read in an afternoon. It grew with the
419
460
  course. Each lesson that taught a new technique — magic sets, stable models,
420
- semirings, incremental maintenance, tabling, subsumption, containment,
461
+ semirings, incremental maintenance, tabling, SLG resolution, subsumption, containment,
421
462
  defeasible logic, the chase — brought a module to run it, and the repository is
422
463
  now several thousand lines. The core idea stayed small, and the code
423
464
  is laid out so you can still read just that: the common core and the
@@ -428,21 +469,23 @@ Measured in lines, comments, docstrings and blank lines included:
428
469
 
429
470
  | Tier | Lines |
430
471
  |---|---|
431
- | the common core (`core.py`: the language, evaluating nothing) | 785 |
432
- | the base engine's evaluator (`datalog.py` up to its CLI section: the module docstring, the import list that re-exports the core, `Program`, `Engine`, aggregation folding, `run_program`) | 395 |
433
- | `--explain`, why-not, printing and the CLI (the rest of `datalog.py`) | 538 |
434
- | the other pluggable engines: magic sets (`magic.py`) and tabling (`tabling.py`), plus the `engines.py` registry (naive evaluation is a flag on the base engine) | 549 |
435
- | the eight extensions | 2,822 |
472
+ | the common core (`core.py`: the language, evaluating nothing; about 270 of these lines arrived with comparisons, constraints, value checks and the warnings) | 1,057 |
473
+ | the base engine's evaluator (`datalog.py` up to its CLI section: the module docstring, the import list that re-exports the core, `Program`, `Engine`, aggregation folding, `run_program`) | 423 |
474
+ | `--explain`, why-not, constraint reports, `--assume`, printing and the CLI (the rest of `datalog.py`) | 635 |
475
+ | the other pluggable engines: magic sets (`magic.py`) and tabling (`tabling.py`), plus the `engines.py` registry (naive evaluation is a flag on the base engine; the fifth engine, SLG, is counted with the extensions) | 700 |
476
+ | the nine extensions | 3,413 |
436
477
 
437
478
  So the smallest complete Datalog system here — parse, check, stratify,
438
- evaluate semi-naively — is the core plus the evaluator, about 1,200
439
- lines. All of it is 5.1k lines of toolkit (every module but the
479
+ evaluate semi-naively — is the core plus the evaluator, about 1,500
480
+ lines. All of it is 6.2k lines of toolkit (every module but the
440
481
  re-export list in `__init__.py`), roughly a quarter of it commentary,
441
- and 3.6k of tests.
482
+ and 4.4k of tests.
442
483
 
443
484
  "Tiny" is a claim about that core and evaluator, and about each module
444
- built on them singly: none of the eleven (`magic.py`, `tabling.py`,
445
- `engines.py` and the eight extensions) exceeds 500 lines, which a test asserts. It is not a
485
+ built on them singly: none of the twelve (`magic.py`, `tabling.py`,
486
+ `engines.py` and the nine extensions) exceeds 500 lines, except
487
+ `slg.py`, allowed 600 because it is tabling plus a scheduler, and a
488
+ test asserts both limits. It is not a
446
489
  claim about the repository, which is a dozen modules because it
447
490
  teaches a dozen things.
448
491
 
@@ -94,7 +94,7 @@ Nothing to install:
94
94
 
95
95
  ```sh
96
96
  git clone https://github.com/andrewgoodchild/tiny-datalog && cd tiny-datalog
97
- python3 tests.py # 326 tests, ~12s
97
+ python3 tests.py # 402 tests, ~20s
98
98
  ```
99
99
 
100
100
  ## Why the language choice decides what you can ask later
@@ -150,7 +150,9 @@ it:
150
150
 
151
151
  Every feature in this repository is a check of that kind: stratification
152
152
  catches circularity, `--models` catches contradiction and ambiguity,
153
- `containment.py` catches redundancy, and `--explain` produces the
153
+ `containment.py` catches redundancy, integrity constraints catch a rule
154
+ set that breaks the policy stated another way, warnings catch the typo
155
+ that silently empties a relation, and `--explain` produces the
154
156
  derivation somebody has to sign off on.
155
157
 
156
158
  Two limits. An engine checks coherence, not intent: a rule set can pass
@@ -161,7 +163,7 @@ the better tool, and that covers most problems.
161
163
 
162
164
  ## What else you can ask it
163
165
 
164
- The worked example above is one row of a table. The full version — 23
166
+ The worked example above is one row of a table. The full version — 32
165
167
  questions, each with the command that answers it and the lesson that
166
168
  builds the machinery — is in
167
169
  [getting started](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/getting-started.md), beside the reading
@@ -194,20 +196,29 @@ is the whole relation the guards are pure overhead.
194
196
  [Lesson 7](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/07-magic-sets.md) works through why.
195
197
 
196
198
  Correctness is checked by a seeded differential fuzzer that generates
197
- stratified programs and demands semi-naive, naive, magic-sets and
198
- tabled evaluation all agree, and that incremental maintenance matches
199
- recomputation under random updates. 400 programs per run;
199
+ stratified programs, aggregates included, and demands that all five
200
+ engines agree; that SLG matches the well-founded model on unstratified
201
+ ones, with and without subsumptive tabling; and that incremental
202
+ maintenance matches recomputation under random updates. 400 programs
203
+ per run;
200
204
  `TINY_DATALOG_FUZZ=3000 python3 tests.py DifferentialFuzzTests` soaks.
201
205
 
202
206
  Answers are also checked against engines this repository did not write.
203
207
  [`conformance/`](https://github.com/andrewgoodchild/tiny-datalog/tree/main/conformance)
204
208
  runs the [datalog-conformance](https://pypi.org/project/datalog-conformance/)
205
- corpus, harvested from Soufflé, Nemo and Crepe, through all four
209
+ corpus, harvested from Soufflé, Nemo and Crepe, through all five
206
210
  strategies, and its defeasible theories, from SPINdle and the papers,
207
211
  through `defeasible.py`: 195 cases pass. Every skip is named with its
208
212
  reason: arithmetic and 10⁵-fact joins, which this course omits on
209
213
  purpose, or cases written for a different logic.
210
214
 
215
+ And the tests themselves are checked: `benchmarks/mutate.py` makes
216
+ each one-line break a bug could make (a `<` for a `<=`, a dropped
217
+ `not`, a deleted statement) and runs the suite against each. At 0.7.0
218
+ the suite caught 91% of 3,322 such mutants. Most of the rest change
219
+ nothing a user could observe, such as a counter's starting value or a
220
+ default limit raised by one; the others are mainly CLI printing.
221
+
211
222
  ## Learning Datalog
212
223
 
213
224
  `lessons/` is a complete course, no prior exposure assumed, every
@@ -217,10 +228,12 @@ observe that the literature advises people building Datalog engines
217
228
  better than people trying to *use* one; this course does both halves
218
229
  on purpose — sixteen lessons where the engine is the explanation, then
219
230
  a lesson on authoring rules that survive review, one on a logic
220
- built for rules with exceptions, and three where the engine goes to
231
+ built for rules with exceptions, and five where the engine goes to
221
232
  work: [authorization](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/20-authorization.md),
222
233
  [program analysis](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/21-program-analysis.md),
223
- and [knowledge graphs and the chase](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/22-knowledge-graphs.md).
234
+ [knowledge graphs and the chase](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/22-knowledge-graphs.md),
235
+ [time and history](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/23-time.md),
236
+ and [memory for a language-model agent](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/24-memory.md).
224
237
  And it is built to be
225
238
  inherited: `git clone`, no dependencies, no hosted anything, and every
226
239
  quoted transcript re-verified by CI — the exercises cannot rot. (For where each
@@ -268,10 +281,9 @@ see [pyDatalog](https://pypi.org/project/pyDatalog/).
268
281
  Deliberate omissions, because saying why teaches more than lacking them
269
282
  quietly:
270
283
 
271
- - **Arithmetic and comparisons.** A built-in isn't a relation you can
272
- enumerate, so it must be *evaluated* the moment its operands bind —
273
- which entangles correctness with join order and forces terms to
274
- become trees. [Lesson 14](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/14-arithmetic.md) is the whole
284
+ - **Arithmetic.** `Z = X + 1` makes values nobody stated, so it can make
285
+ a relation infinite, and the termination theorem goes with it.
286
+ [Lesson 14](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/14-arithmetic.md) is the whole
275
287
  story, including what to do instead.
276
288
  - **Indexes and join planning.** Every join is a nested loop so the
277
289
  algorithms stay one-screen readable. It is also why the magic-sets
@@ -284,7 +296,10 @@ quietly:
284
296
 
285
297
  Aggregation used to be on this list;
286
298
  [lesson 13](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/13-aggregation.md) is what promoting an omission
287
- into a feature looks like.
299
+ into a feature looks like. Comparisons (`<`, `<=`, `>`, `>=`, `=`,
300
+ `!=`) used to share arithmetic's entry. They check values and never
301
+ make them, so they can only filter, and lesson 14's own argument lets
302
+ them in; [lesson 23](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/23-time.md) puts them to work.
288
303
 
289
304
  ## Using it in your own project
290
305
 
@@ -321,8 +336,27 @@ engine = run_program(rules, facts={
321
336
  engine.query("exposed(S, C)") # [{'S': 'app', 'C': 'cve_2026_0001'}]
322
337
  ```
323
338
 
339
+ A rule with no head is an integrity constraint, a situation that must
340
+ never arise. `engine.violations()` lists each broken one with its
341
+ counterexamples, and the command line prints them and exits with
342
+ status 3:
343
+
344
+ ```python
345
+ checked = run_program(rules + ":- exposed(S, C).", facts={
346
+ "depends": [("app", "lib"), ("lib", "core")],
347
+ "service": ["app"],
348
+ "vulnerable": [("core", "cve_2026_0001")],
349
+ })
350
+ checked.violations() # [(constraint, [{'S': 'app', 'C': 'cve_2026_0001'}])]
351
+ ```
352
+
353
+ For agents, `skills/tiny-datalog/SKILL.md` is an Agent Skill that
354
+ teaches a coding agent the language and the habits (explain before
355
+ trusting, state properties as constraints); copy it into your agent's
356
+ skills directory.
357
+
324
358
  The command-line interface installs too, as `tiny-datalog` (and
325
- `tiny-datalog-semiring`, `-tabling`, `-incremental`, `-subsumption`,
359
+ `tiny-datalog-semiring`, `-tabling`, `-slg`, `-incremental`, `-subsumption`,
326
360
  `-containment`, `-defeasible`, `-prolog` for the other engines and the
327
361
  extensions):
328
362
 
@@ -338,16 +372,20 @@ installed package; clone the repository for that.
338
372
  ```
339
373
  tiny_datalog/ the code you read, in three tiers:
340
374
  core.py the common core — the language every module shares:
341
- AST, parser, safety checks, stratification, matching,
342
- formatting, query helpers
343
- engines — four strategies, one answer (engines.py lists them):
375
+ AST, parser, safety checks, comparisons, stratification,
376
+ matching, formatting, query helpers, warnings
377
+ engines — five strategies, one answer (engines.py lists them):
344
378
  datalog.py the base engine: semi-naive and naive bottom-up
345
- evaluation, aggregation, --explain / why-not, the CLI
379
+ evaluation, aggregation, integrity constraints,
380
+ --explain / why-not, --assume, the CLI
346
381
  magic.py the magic-sets rewriting (a program-to-program pass)
347
382
  tabling.py tabled top-down evaluation (iterative QSQR)
348
- engines.py the registry and the interface the four share
383
+ engines.py the registry and the interface the five share (the
384
+ fifth is SLG, from slg.py below, held to stratified
385
+ programs)
349
386
  extensions — other questions asked of the same programs:
350
387
  semantics.py grounding, stable models, the well-founded model
388
+ slg.py SLG resolution: the well-founded model, top-down
351
389
  semiring.py semiring-valued evaluation (costs, counts, provenance,
352
390
  probabilities)
353
391
  incremental.py insertions + DRed deletions over a live materialisation
@@ -359,16 +397,19 @@ tiny_datalog/ the code you read, in three tiers:
359
397
  acyclicity
360
398
  *.py three-line launchers, so `python3 datalog.py ...` works
361
399
  straight from a checkout with nothing installed
362
- programs/ teaching programs, numbered by the lesson that uses
363
- them (00-* are the README's examples)
364
- lessons/ getting started, glossary, and lessons 0–22
400
+ programs/ teaching programs, named for what they model; each
401
+ lesson says which ones it runs
402
+ lessons/ getting started, glossary, and lessons 0–24
365
403
  exercises/ worked answers, verified by the test suite
366
404
  cases/ golden test cases — add one without writing Python
405
+ skills/ an Agent Skill that teaches coding agents to use the engine
367
406
  conformance/ the external datalog-conformance corpus (Soufflé, Nemo,
368
407
  Crepe, SPINdle), run against every evaluation strategy
369
408
  benchmarks/ scaled input generators (chain/tree/clique/grid, an EL
370
- ontology, and the N-queens puzzle)
371
- tests.py 326 tests: every shipped program and exercise answer is
409
+ ontology, and the N-queens puzzle), and mutate.py,
410
+ which breaks the code one line at a time to measure
411
+ how much of it the tests would notice (91% at 0.7.0)
412
+ tests.py 402 tests: every shipped program and exercise answer is
372
413
  executed, a conformance suite runs every query through
373
414
  every engine that handles it, and a seeded fuzzer checks
374
415
  the same property on random programs
@@ -384,7 +425,7 @@ used.
384
425
  This project started as an attempt at a tiny implementation of
385
426
  Datalog, small enough to read in an afternoon. It grew with the
386
427
  course. Each lesson that taught a new technique — magic sets, stable models,
387
- semirings, incremental maintenance, tabling, subsumption, containment,
428
+ semirings, incremental maintenance, tabling, SLG resolution, subsumption, containment,
388
429
  defeasible logic, the chase — brought a module to run it, and the repository is
389
430
  now several thousand lines. The core idea stayed small, and the code
390
431
  is laid out so you can still read just that: the common core and the
@@ -395,21 +436,23 @@ Measured in lines, comments, docstrings and blank lines included:
395
436
 
396
437
  | Tier | Lines |
397
438
  |---|---|
398
- | the common core (`core.py`: the language, evaluating nothing) | 785 |
399
- | the base engine's evaluator (`datalog.py` up to its CLI section: the module docstring, the import list that re-exports the core, `Program`, `Engine`, aggregation folding, `run_program`) | 395 |
400
- | `--explain`, why-not, printing and the CLI (the rest of `datalog.py`) | 538 |
401
- | the other pluggable engines: magic sets (`magic.py`) and tabling (`tabling.py`), plus the `engines.py` registry (naive evaluation is a flag on the base engine) | 549 |
402
- | the eight extensions | 2,822 |
439
+ | the common core (`core.py`: the language, evaluating nothing; about 270 of these lines arrived with comparisons, constraints, value checks and the warnings) | 1,057 |
440
+ | the base engine's evaluator (`datalog.py` up to its CLI section: the module docstring, the import list that re-exports the core, `Program`, `Engine`, aggregation folding, `run_program`) | 423 |
441
+ | `--explain`, why-not, constraint reports, `--assume`, printing and the CLI (the rest of `datalog.py`) | 635 |
442
+ | the other pluggable engines: magic sets (`magic.py`) and tabling (`tabling.py`), plus the `engines.py` registry (naive evaluation is a flag on the base engine; the fifth engine, SLG, is counted with the extensions) | 700 |
443
+ | the nine extensions | 3,413 |
403
444
 
404
445
  So the smallest complete Datalog system here — parse, check, stratify,
405
- evaluate semi-naively — is the core plus the evaluator, about 1,200
406
- lines. All of it is 5.1k lines of toolkit (every module but the
446
+ evaluate semi-naively — is the core plus the evaluator, about 1,500
447
+ lines. All of it is 6.2k lines of toolkit (every module but the
407
448
  re-export list in `__init__.py`), roughly a quarter of it commentary,
408
- and 3.6k of tests.
449
+ and 4.4k of tests.
409
450
 
410
451
  "Tiny" is a claim about that core and evaluator, and about each module
411
- built on them singly: none of the eleven (`magic.py`, `tabling.py`,
412
- `engines.py` and the eight extensions) exceeds 500 lines, which a test asserts. It is not a
452
+ built on them singly: none of the twelve (`magic.py`, `tabling.py`,
453
+ `engines.py` and the nine extensions) exceeds 500 lines, except
454
+ `slg.py`, allowed 600 because it is tabling plus a scheduler, and a
455
+ test asserts both limits. It is not a
413
456
  claim about the repository, which is a dozen modules because it
414
457
  teaches a dozen things.
415
458
 
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "tiny-datalog"
7
- version = "0.5.0"
7
+ version = "0.7.0"
8
8
  description = "A Datalog engine whose core you can read in an afternoon, and a course built on it"
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -48,6 +48,7 @@ tiny-datalog = "tiny_datalog.datalog:main"
48
48
  tiny-datalog-prolog = "tiny_datalog.prolog:main"
49
49
  tiny-datalog-semiring = "tiny_datalog.semiring:main"
50
50
  tiny-datalog-tabling = "tiny_datalog.tabling:main"
51
+ tiny-datalog-slg = "tiny_datalog.slg:main"
51
52
  tiny-datalog-incremental = "tiny_datalog.incremental:main"
52
53
  tiny-datalog-subsumption = "tiny_datalog.subsumption:main"
53
54
  tiny-datalog-containment = "tiny_datalog.containment:main"
@@ -9,10 +9,12 @@ are their public surface, re-exported here so that library use reads as
9
9
 
10
10
  `tiny_datalog.engines` lists the pluggable engines, which all give the
11
11
  same answers: semi-naive and naive (`datalog`), `magic` (goal-directed
12
- rewriting) and `tabling` (top-down with memoing).
12
+ rewriting), `tabling` (top-down with memoing) and `slg` (SLG
13
+ resolution, held to stratified programs).
13
14
 
14
15
  Everything else is an extension built on the core, asking a different
15
16
  question of a program: `semantics` (stable and well-founded models),
17
+ `slg` (the well-founded model top-down, by SLG resolution),
16
18
  `semiring` (provenance-weighted evaluation), `incremental` (maintenance
17
19
  under updates), `subsumption` (KL-ONE style classification),
18
20
  `containment` (query containment), `defeasible` (rules with exceptions
@@ -36,7 +38,7 @@ from tiny_datalog.datalog import (
36
38
  format_atom, format_fact,
37
39
  )
38
40
 
39
- __version__ = "0.5.0"
41
+ __version__ = "0.7.0"
40
42
 
41
43
  __all__ = [
42
44
  "Var", "Const", "Struct", "Atom", "Literal", "Rule",
@@ -73,7 +73,8 @@ from dataclasses import dataclass
73
73
 
74
74
  from tiny_datalog.core import (
75
75
  _format_value, aggregate_of, Atom, cli, Const, DatalogError, Literal,
76
- match, parse, parse_query_atom, read_program, Rule, Var, validate)
76
+ match, parse, parse_query_atom, read_program, refuse_extras, Rule, Var,
77
+ validate)
77
78
  from tiny_datalog.datalog import Engine, Program
78
79
 
79
80
 
@@ -133,6 +134,9 @@ def check(clauses):
133
134
  The core's checks apply to a *skeleton* of each rule in which the
134
135
  existential variables are replaced by a placeholder constant: that
135
136
  is exactly "safe, except for the variables we mean to invent"."""
137
+ # an invented value has no order to compare, and denial
138
+ # constraints over nulls are a theory of their own
139
+ refuse_extras(clauses, "the chase")
136
140
  for c in clauses:
137
141
  if c.retract:
138
142
  raise DatalogError("a retraction is an update, not a statement:"
@@ -42,7 +42,7 @@ import sys
42
42
 
43
43
  from tiny_datalog.core import (
44
44
  aggregate_of, cli, Const, DatalogError, parse, read_program, validate,
45
- Var)
45
+ Var, is_comparison)
46
46
 
47
47
 
48
48
  def _extend(mapping, source_args, target_args):
@@ -93,6 +93,12 @@ def _bodies(rule):
93
93
  raise DatalogError(
94
94
  "containment by homomorphism is a conjunctive-query "
95
95
  "result; negation needs different theory: %s" % rule)
96
+ if is_comparison(lit):
97
+ # Klug (1988): with comparisons one homomorphism no longer
98
+ # suffices -- every ordering of the variables must be checked
99
+ raise DatalogError(
100
+ "containment by homomorphism is a conjunctive-query "
101
+ "result; comparisons need different theory: %s" % rule)
96
102
  if aggregate_of(rule.head):
97
103
  # sum/count see duplicates; Chandra–Merlin is about sets.
98
104
  raise DatalogError(
@@ -198,6 +204,10 @@ def main(argv=None):
198
204
  print("%s\n (skipped: negation is outside the theory)"
199
205
  % rule)
200
206
  continue
207
+ if any(is_comparison(lit) for lit in rule.body):
208
+ print("%s\n (skipped: comparisons are outside the theory)"
209
+ % rule)
210
+ continue
201
211
  if aggregate_of(rule.head):
202
212
  print("%s\n (skipped: aggregation is outside the theory)"
203
213
  % rule)