SWI-Prolog Capability Atlas

This folder is a systematic capability survey of SWI-Prolog — the dialect embedded in-process by orchestrata as its governance/policy brain — swept from the official swi-prolog.org documentation on 2026-07-29. Each of the ten topic pages was written against the actual manual sections and package documents (the exact URLs read are cited in each page's ## Sources section), not from folklore or secondhand blog posts. Every page follows the same contract:

1. Full predicate reference — every major predicate/directive of the subsystem with its signature, determinism, and semantics explained in full sentences.
2. Runnable examples — complete SWI-Prolog code blocks taken or adapted from the manual, long enough to paste into swipl and run.
3. A mermaid diagram of the subsystem's architecture or data flow.
4. ## Pitfalls and gotchas — the real caveats the manual documents (and a few it only implies), because these subsystems fail in non-obvious ways.
5. ## How orchestrata can leverage this — 3–6 concrete proposals grounded in the real codebase: named rule files (governance.pl, kg_relevance.pl, test_schedule.pl, …), named Python seams (core/prolog_adapter.py, governance/prolog_gate.py, orchestrator/prolog_worker.py), and named infrastructure (the redis-queue container at 10.53.1.10, the Memgraph orchgraph cluster at 10.53.1.160).

The cross-project consolidation of all those leverage sections — deduplicated, ranked, with code sketches — lives in the companion capstone page: Prolog Leverage Roadmap for orchestrata.

Why this folder exists

Orchestrata already runs SWI-Prolog in production: 22 rule files consulted through the janus bridge cover governance gating, intent NL parsing, symbolic knowledge-graph reasoning, and CLP(FD) test scheduling. But the live-analysis audit that preceded this sweep found the project uses a narrow slice of what the runtime ships: no plunit, no Prolog-side threads, no library(redis), no semweb, no engines, no persistency, tabling only in the KG tier, CLP(FD) only in one file, DCGs only in one grammar. Each topic page documents one of those unused (or under-used) subsystems end-to-end so that future design work can reach for the right primitive with the manual semantics already digested.

The topic pages

How the subsystems compose

The pages are written to stand alone, but the subsystems are not islands — SWI-Prolog's power for a system like orchestrata comes from how they stack:

• janus is the membrane. Everything orchestrata does today flows through it (janus). Every other capability on this map is reachable through that membrane without new infrastructure: a Python thread calling query_once/1 can transparently hit a tabled predicate, a CLP(FD) model, a DCG, or a redis/3 call — the bridge does not care what the goal does.
• Tabling and dynamic predicates are two halves of one mechanism. Incremental tabling (tabling) only invalidates when the dynamic predicates underneath are declared as incremental (modules-dynamic-state) — both ends must opt in, and orchestrata's ground-facts-only assertz doctrine is exactly the purity precondition that makes tabling the governance corpus safe.
• Threads, queues, and engines are three different concurrency shapes. OS threads (threads) give preemptive parallelism with copied-term queues; engines (engines-coroutines) give suspendable sequential computations with per-pull thread attachment — a frozen proof search or a resumable counterexample cursor is an engine job, a parallel gate-evaluation pool is a thread job. thread_wait/2 turns the shared dynamic DB into a condition variable, which is what makes push-based (rather than polled) gating possible.
• CLP and DCG are both "relations, not procedures". CLP(FD) constraints (clpfd) work in all directions the way pure DCGs (dcg) parse and generate from the same rules; both replace imperative Python loops with declarative specifications the explain/provenance machinery can reason about.
• Redis and semweb are the two native I/O stores. library(redis) (redis) reaches the project's hot store directly from rule code; the RDF store (semweb-graphs) offers named-graph snapshots, built-in transitive closure, and a crash-safe journaled audit log — capabilities the hand-rolled ground-fact projections currently reimplement or lack.
• plunit closes the loop. Every capability above becomes safely adoptable only when the rule files have native tests (plunit) — which orchestrata currently has zero of (.plt count in the repo: 0).

Overview diagram

Solid arrows are data paths; dashed annotations mark where orchestrata stands today (USED / UNUSED / PROPOSED). The asymmetry is the whole story: the janus membrane and the tabling/DCG/CLP islands behind it are production-proven, while the entire right-hand column of I/O and lifecycle machinery (redis, semweb, persistency, plunit, threads, engines) is dark.

Orchestrata touchpoint summary

A condensed map of where each subsystem meets the codebase — the leverage roadmap page expands every row into a concrete build item:

Facts worth remembering

Datapoints from the sweep that repeatedly change design decisions — each is documented in full on its topic page:

• janus failure is silent, not raised: query_once returns {'truth': False} with None bindings on failure; only -ERR-class conditions raise. An unclosed janus.query() iterator leaves SWI inconsistent and typically crashes the process — always use the context manager. (janus)
• Capitalised names in a goal string are Python-bound inputs — string interpolation into goals is a documented injection risk and the root of orchestrata's ground-facts-only assertz doctrine. apply_once/cmd skip goal-string parsing entirely and are the documented faster path. (janus)
• Incremental tabling needs both ends to opt in: an incremental table over a non-incremental dynamic predicate gets no dependency-graph edge and silently never invalidates. Granularity is the whole table, not the clause. (tabling)
• Subsumptive tabling is only sound for pure predicates — the manual's own benchmark drops 13 s / 150 M inferences to 0.015 s / 140 K, but answers come from more general completed tables, so impure predicates give wrong results. (tabling)
• Message queues copy terms both ways and thread_get_message/1 does selective receive: it unifies against queued terms and skips (leaves) non-matching ones. The /3 variants with timeout/deadline fail silently on expiry — timeout(0) is a poll. (threads)
• thread_wait/2 + thread_update/2 turn the dynamic DB into a condition variable — block until a goal over dynamic predicates becomes true, woken per-module on assert/retract. This is the primitive for push-based (zero-poll) gating. (threads)
• A named Redis server is one mutex-serialised socket, not a pool; redis_connect/3 handles are unlocked and do not reconnect by default. An all-nil reply makes redis/3 fail (semidet) rather than return nulls. (redis)
• plunit flags nondeterministic success by default — a supposedly-det test body that succeeds with a leftover choicepoint is reported unless the test says nondet; set/1 outcomes catch duplicate solutions. cleanup always runs, even on exceptions; a failing condition skips where a failing setup errors. (plunit)
• all_distinct/1 is domain-consistent and can prove infeasibility before labeling; the manual recommends it over the cheaper all_different/1. labeling/2 over finite domains is complete, terminating, and non-redundant, with min/max branch-and-bound built in. (clpfd)
• cumulative/2 requires every task field to be an integer or bounded FD variable — task(Start,Duration,End,Consumption,Id) terms with an unbounded field make it useless. (clpfd)
• Engines are ~20 KB suspendable Prolog VMs, not OS threads — they attach to the calling thread per engine_next/2 pull, and engine_yield/1 raises permission_error inside a C callback (directly relevant under janus py_call frames). (engines-coroutines)
• rdf_reachable/3 is built-in cycle-safe BFS transitive closure with shortest hop distance; named graphs are a 4th triple dimension with O(1) bulk teardown (rdf_unload_graph/1); the RDF persistency .jrn journal is a crash-safe replayable log of timestamped assert/retract terms. sparql_query/3 speaks SPARQL-over-HTTP only — it cannot talk Bolt to Memgraph. (semweb-graphs)
• DCG nonterminals must never be called directly — -->/2 rules compile to clauses with two hidden difference-list arguments; phrase/3 type-checks and rejects SWI-7 strings as list arguments (use backquoted text or string_codes/2); pure grammars run backwards for generation. (dcg)
• Modules resolve by filename, not module name, use_module/1 imports are weak symbols (local definitions override), and same-name exports from two modules are a hard error requiring use_module/2. The ISO logical update view means a running goal sees exactly the clauses that existed when it started. (modules-dynamic-state)

Reading order

For a first pass, read in dependency order rather than table order:

1. janus — the membrane everything crosses; understand the truth-value dict, the iterator-close hazard, and why assertz is ground-facts-only.
2. modules-dynamic-state — modules, dynamic/1, and the logical update view; prerequisites for reading any rule file critically.
3. tabling — the most consequential single capability for the governance corpus (incremental tables = gate decisions as trie lookups).
4. plunit — because nothing else should ship untested.
5. Then in any order: threads, redis, clpfd, dcg, semweb-graphs, engines-coroutines.
6. Finish with the leverage roadmap, which turns the ten ## How orchestrata can leverage this sections into one ranked, deduplicated build plan.

Provenance and maintenance

• Source of truth: the official SWI-Prolog manual and package docs at swi-prolog.org, read 2026-07-29 (SWI-Prolog 9.x documentation). Each topic page cites the exact pldoc/man?section= and pldoc/doc_for?object= URLs it was written from.
• Project claims (file names, line numbers, container addresses) come from a live analysis of the orchestrata codebase performed the same day; when orchestrata's bridge or rule layout changes, the touchpoint table above and the leverage roadmap are the pages to update — the ten topic pages are project-independent references and should only change when SWI-Prolog itself does.
• Conventions: predicate indicators are written name/arity, DCG nonterminals name//arity; all code blocks are SWI-Prolog syntax (SWI-7 strings, dicts where noted).

Sources

The seed table-of-contents pages for the sweep (each topic page cites its own deeper URLs):

• https://www.swi-prolog.org/pldoc/man?section=threads — threads, queues, signalling
• https://www.swi-prolog.org/pldoc/man?section=tabling — SLG resolution, all tabling modes
• https://www.swi-prolog.org/pldoc/man?section=clp — constraint programming overview (clpfd, clpb)
• https://www.swi-prolog.org/pldoc/man?section=DCG — definite clause grammars
• https://www.swi-prolog.org/pldoc/man?section=engines — engines/interactors
• https://www.swi-prolog.org/pldoc/man?section=modules — module system
• https://www.swi-prolog.org/pldoc/man?section=db — dynamic predicates and the update view
• https://www.swi-prolog.org/pldoc/man?section=janus — the janus bidirectional bridge
• https://www.swi-prolog.org/pldoc/doc_for?object=section(%27packages/plunit.html%27) — plunit
• https://www.swi-prolog.org/pldoc/doc_for?object=section(%27packages/redis.html%27) — library(redis)
• https://www.swi-prolog.org/pldoc/doc_for?object=section(%27packages/semweb.html%27) — semweb/RDF
• https://www.swi-prolog.org/pldoc/man?section=ugraphs — library(ugraphs)
• https://www.swi-prolog.org/pldoc/man?section=coroutining — freeze/2, when/2, dif/2
• https://www.swi-prolog.org/pldoc/man?section=persistency — library(persistency)
• https://www.swi-prolog.org/pldoc/man?section=settings — library(settings)