ftl-reasons Code Expert

The ftl-reasons Code Expert knowledge base captures deep, systematized understanding of a Truth Maintenance System called "reasons" — a Python library and CLI tool that manages networks of beliefs with justifications, propagation, retraction, and contradiction resolution. The system lets agents (including LLMs) maintain an external epistemic memory where beliefs can be added, justified by other beliefs, retracted with cascading consequences, and challenged through dialectical processes. This wiki documents not just what the code does, but the invariants it upholds, the edge cases it handles, and the architectural decisions that hold the system together.

The 18 topics reveal a system of considerable depth. At the core are justification-propagation and nogood-backtracking, which implement the TMS engine itself — how beliefs flow from premises through derived nodes, and how contradictions trigger principled retraction. Surrounding this core are topics like belief-revision-governance, convergence-equilibria, and determinism-traceability, which document the higher-order properties the system guarantees: that revision terminates, that propagation is deterministic, that outputs are reproducible. The practical surface area is covered by api-layer, cli packaging, persistence-backends (SQLite-based, with careful rowid ordering), and external-integration, which governs how beliefs from outside agents are imported with trust boundaries intact.

The network contains 1101 beliefs across those 18 topics, with roughly two-thirds currently IN and one-third OUT. The mix of premises and derived beliefs reflects a process where an expert agent explored the codebase, recorded observations as premises, then synthesized higher-level claims from those observations. The derive-pipeline, deduplication, and compact-module topics document the machinery that manages this synthesis process itself — the system is partly self-describing, containing beliefs about how beliefs are created and maintained.

The 386 OUT beliefs are particularly telling. Many of them are ambitious compositional claims — beliefs like "all transformations are deterministic, traceable, and boundary-safe" or "self-correction spans creation and maintenance" — that attempted to unify multiple properties into single sweeping assertions. Their retraction shows the network refining its understanding: broad claims got replaced by more precise, individually grounded beliefs that could survive scrutiny. This pattern of initial overreach followed by decomposition into verified specifics is a sign of genuine epistemic progress, not failure.

This knowledge base is valuable because it makes a complex, invariant-rich codebase navigable and auditable. A developer encountering the reasons system for the first time can trace exactly why a design choice was made, see which properties have been verified versus retracted, and understand the dependency structure between guarantees. The wiki transforms what would otherwise be implicit knowledge — scattered across code comments, commit messages, and the original developer's memory — into a structured, queryable network where every claim is justified and every retraction is explained.