TruthWeaver.DataSources.Json 1.0.0-prealpha-2026-10-18T220658Z

TruthWeaver

A general-purpose Strong Kleene (K3) expression engine for .NET. Every expression evaluates to one of three values: True, False or Unknown. The engine never silently turns Unknown into True or False. You author a rule once as text, compile it into an immutable tree, and evaluate it many times against whatever application context you supply: a user, a request, a resource, or anything else.

<details> <summary><strong>Table of contents</strong></summary>

• TruthWeaver
  • What it is (and isn't)
  • Requirements
  • Getting started
  • Packages
  • Features
  • Documentation
  • License

</details>

What it is (and isn't)

TruthWeaver answers one question: what is the truth value of this expression right now, for this context? The answer is True, False or Unknown. The engine knows about the operators, terms and evaluation. It does not know about permissions, workflows or policies. You build those on top of it. A permission check ("can the current user do X") is one consumer of the engine, not part of it.

Project and Collapse are methods on the result, not rule operators. See Result transformations. FORALL and EXISTS range over a registered collection. See Quantifiers. The vocabulary and the predicate-author contract are in CONTEXT.md. Release status, version policy and the migration guide for each breaking change are in CHANGELOG.md.

Requirements

Building from source needs at least the SDK version in global.json, currently 11.0.100-rc.1.26425.128. The setting rollForward: latestMajor with allowPrerelease: true accepts any later major .NET SDK on the machine, preview or RC included. The file does not pin that exact patch.

Getting started

1. Reference the packages you need. A service that only implements predicates references TruthWeaver.Abstractions. A host that authors and evaluates rules references TruthWeaver, and TruthWeaver.Yaml for YAML. See Packages.

   <ProjectReference Include="..\TruthWeaver\TruthWeaver.csproj" />
   

2. Implement a predicate. The simplest shape is a class implementing IPredicate<TContext>. A predicate returns a three-valued TruthValue. Return TruthValue.Unknown when the answer is legitimately indeterminate (that is a normal result and records no fault), and throw only for a genuine failure:

   public sealed class LovesPineapple : IPredicate<Customer>
   {
       public static PredicateSchema Schema =>
           PredicateSchema.NoArguments("lovesPineapple", "Loves Pineapple", "Does this customer like pineapple on pizza?");
   
       public ValueTask<TruthValue> EvaluateAsync(Customer customer, PredicateArguments args, CancellationToken ct) =>
           ValueTask.FromResult(customer.LovesPineapple ? TruthValue.True : TruthValue.False);
   }
   

3. Register it and compile a rule:

   PredicateRegistry<Customer> registry = PredicateRegistry<Customer>.CreateBuilder().Add<LovesPineapple>().Build();
   RuleCompiler<Customer> compiler = new(registry);
   
   if (!compiler.TryCompile("lovesPineapple", out CompiledRule<Customer>? rule, out EquatableArray<Diagnostic> diagnostics))
   {
       // diagnostics explains why - surface it to whoever authored the rule.
       return;
   }
   

4. Evaluate it against a context:

   Decision decision = await rule.EvaluateAsync(customer, serviceProvider, cancellationToken: ct);
   
   if (decision.IsSatisfied)
   {
       // allowed
   }
   

The lifecycle is: implement, register, compile once, evaluate many times. The Consumer sample shows these steps with dependency injection and a test. The PredicateLibrary sample shows a project that defines predicates and references TruthWeaver.Abstractions alone. The DataSource sample shows a JSON data source and a rule that reads a value from it. Examples builds from here to named arguments, the full operator set and a worked example in rule text, JSON and YAML.

Packages

The dependencies and contents of each package are in Packages.

Features

• Strong Kleene (K3) evaluation. A predicate fault or an Unknown answer gives Unknown, never a thrown exception or a silently coerced False.
• The full K3 operator set, with symbol spellings, plus the external operators COALESCE and the inspections. Every notation compiles to the same tree.
• Rule text, JSON, YAML and RuleBuilder as ways to author a rule.
• Rewrites that preserve value, rule equivalence and structural diffing.
• A K3 analyzer that flags sub-expressions that are True or False for every assignment, and structured diagnostics for every authoring error.
• Per-evaluation memoization, a fault budget, an exhaustive mode and an overall evaluation timeout.
• Scoped dependency injection for class-based predicates, structured logging and a "TruthWeaver" Meter for metrics.
• Mermaid, HTML, Graphviz DOT and plain-text rendering of a compiled rule, optionally colored by one evaluation.
• Ready-made predicates and test support in TruthWeaver.Predicates and TruthWeaver.Testing.

Documentation

• Strong Kleene (K3) reference: the meaning of every operation, with truth tables, syntax and evaluation rules.
• Glossary: the vocabulary of TruthWeaver, including the terms that are new or easy to confuse.
• Architecture: the source layout, the compilation pipeline and the evaluation flow.
• Packages: the contents and dependencies of each package.
• Rule text: the grammar, grouping delimiters, whitespace and case.
• Rule formats: how to choose between rule text, JSON and YAML, and how to convert between them.
• RuleBuilder, outlines and diagrams: assemble a rule in code, describe it and draw it.
• Equations: print a rule as a flat infix equation in Unicode, LaTeX, AsciiMath, a C-style notation, MathML, Typst or plain ASCII.
• HTML and Graphviz DOT: print a rule as an HTML fragment for a web page, or as a DOT graph for Graphviz.
• Truth tables: print the Strong K3 or classical truth table of a rule in Markdown, CSV, JSON, HTML or LaTeX.
• Rewriting rules and rule equivalence: transform a rule, check that two rules are equivalent, and find whether a new version is looser or tighter. Which rewrite to use helps you choose a rewrite, Simplify describes the simplifier, and Normal forms covers NNF, CNF and DNF. Rewriting examples and Normal form examples show each rewrite in four notations.
• Predicate types: the four registration shapes and the ready-made predicates.
• Predicate conventions: how the built-in predicates treat case, whitespace, range ends, null values and culture.
• Predicate source generator: register [Predicate] methods with generated code, and compare it with hand-written registration.
• Predicate harness: check a predicate for determinism, boundary values, schema conformance and cancellation.
• Rule fuzzer: check random rules over the predicates of a registry against a Strong Kleene oracle.
• Testing assertions: assert that two rules are equivalent, that a rewrite is sound, and check a Decision in a test.
• Rule tests: write test cases for a rule in YAML, with a value for each term, and run them with truthweaver test or from C#, with a JUnit report for CI.
• Data sources: supply variable values to a rule.
• Batch evaluation: evaluate one rule against many contexts, in order, with bounded parallelism.
• Rule coverage: find the terms and branches of a rule that never decide, are always Unknown or fault, over many decisions.
• Shadow replay: run contexts through two versions of a rule and list the contexts whose decision changed, with both traces.
• What would change a decision: the smallest sets of term changes that would make a rule True (or False), for a "what to fix" list.
• Decision records: store a decision as JSON for an audit log, with the rule identity and the evaluation options, and read it back for replay.
• ASP.NET Core authorization: decide authorization policies and resource-based checks with rules, fail-closed, with the decision for logs and problem-details responses.
• Policy sets: combine policies with a target, an effect and a priority by deny-overrides, permit-overrides or first-applicable, fail-closed on Unknown.
• Rule store: load named rules from IConfiguration, compile once, cache by hash and swap on reload, keeping the last good rule.
• Command line: the truthweaver .NET tool: validate, convert, format, print, export, report, diff, evaluate and test rules from the shell, with JSON output, SARIF and documented exit codes.
• Terminal UI: the truthweaver-tui .NET tool: edit a rule in rule text, JSON or YAML with live diagnostics, the last valid tree on an error, undo and redo, format, open and save, in linked panes; then give each term a value and see the decision, the colored trace and the reason for each node, edit the tree with checked structural edits and a palette, and try the rewrites (Simplify with its steps, the normal forms) before you accept one, with an equivalence check against the saved version.
• Tool core: the library under the command line and the terminal UI: load, detect, extract and convert rules, validate them in levels with statistics, write diagnostics as text, JSON or SARIF, export every artifact with a manifest, write a Markdown report, render images with Graphviz or the Mermaid CLI, the truthweaver.json file, stub values, data files and deterministic output.
• Examples: eight worked examples, from one predicate to a full rule. Which printer to use lists the printers for each job, the same rule side by side compares the notations, and operator styles shows the symbol sets.
• Reading diagnostics: the Diagnostic members, lint rules and diagnostics for JSON and YAML rules.
• Benchmarks: the benchmark commands and the committed baseline.
• Documentation examples: how the examples in the documentation are tested.
• Contributing: what the pre-commit hook and scripts/format-all.cs do, and how a package version is made.
• CONTEXT.md: the domain vocabulary and the predicate-author contract.

License

Apache License 2.0. See LICENSE.

See CLAUDE.md for development rules, required validation commands and formatting and testing conventions.