factbag 0.0.0-stage → 0.1.0-alpha.7

package/CHANGELOG.md

@@ -0,0 +1,108 @@
+# factbag
+
+## 0.1.0-alpha.7
+
+No changes in this release.
+
+## 0.0.0-alpha.6
+
+### Minor Changes
+
+- 7225a51: Add `firstOfMonth(year, month)`, a date-valued arithmetic term for the first day of a month at UTC midnight, and `yearOf(date)`, a number-valued term for a date's UTC calendar year. Rules can now derive a year's bounds, such as `firstOfMonth(Y, 1)` and `sub(firstOfMonth(add(Y, 1), 1), 86_400_000)`, instead of looking them up in asserted calendar facts. A month outside 1 to 12, or a year that is not a whole number, throws `PrimitiveArithmeticProgrammerError` rather than rolling over. The query API adds `FirstOfMonthGoal` and the `"firstOfMonth"` arithmetic kind.
+- 5114b2f: Show the `citation` and `justification` recorded with a piece of evidence in its explanation, beside its `source`. An evidence reason no longer repeats the claim of the step it supports; it names its own claim only when that differs, as in a conflict, or when the evidence has no provenance. `EvidenceReason.quote`, which was never filled, is replaced by `citation`.
+- eab3679: Explain a rule application with the rule alone, `eligible(P) iff not(active_sanction(P))`, without the trailing `, with P = alice`. The values a rule was applied to are already written into the claim it supports and the claims it rests on.
+- e4b343e: Add a `budget` option to `explainJudgment`: the most claims to explain. The conclusion is always explained, then the claims that decided it before those that were evaluated and changed nothing, and those near the conclusion before those far from it. A claim that rests on claims left out names them, with their values, under `notShown`. Without a budget the whole proof is explained, as before; written as JSON a deep proof repeats each shared claim on every path to it, so give a budget when explaining a judgment in text.
+
+### Patch Changes
+
+- 7f26b45: Write explanation claims with the values their variables hold: `lte(1000, 36900) = true` instead of `lte(I, 36900) = true`, and `spouse(alice, S) = false` instead of `spouse(P, S) = false`. A variable with no value keeps its name. A term that computes a value states it, such as `H = max(1000, 500) = 1000`, instead of ending in `= true`.
+- b7c85ff: Explain a comparison, arithmetic term or aggregate as `computed` instead of `no supporting evidence or rule was found`. When one could not be evaluated because a variable has no value, the explanation names the variable, such as `X has no value`.
+- ed6ec84: Write a date at UTC midnight as a day in explanations, `2015-12-31` instead of `2015-12-31T00:00:00.000Z`. A date with a time of day keeps its full timestamp.
+- 15391f2: Rest a rule application directly on the subgoals of its body in explanations. When a rule's body is an `and` or an `or`, the explanation no longer has a node that restates the body between the rule and its subgoals: the rule's `given` lists the subgoals themselves. A compound nested inside a body is still its own node, and so is a body that is a single atom or a negation.
+- ecbd8d9: Stop naming the solver's temporaries, such as `$tmp0`, in explanations. A nested arithmetic term is written as the term and its value, `mul(1000, 0.15) = 150`; a term that could not be computed stands in for its result wherever that is used, `gte(add(X, 1), 18) = unknown`; and a rule's `with ...` list gives only the rule's own variables.
+
+## 0.0.0-alpha.5
+
+### Minor Changes
+
+- 19ac508: **Breaking:** errors have their own entry point, `factbag/exceptions`. `ProgrammerError`, `ExclusiveDefinitionProgrammerError`, `PrimitiveArithmeticProgrammerError`, and `UnsafeUnboundVariableProgrammerError` move there from `factbag/kb`. `UnconstructiveRecursionProgrammerError`, which the solver raised but no entry point exported, is now exported too. `UnsupportedPredicateError` moves there from `factbag/jev/errors` and now extends `ProgrammerError`.
+- 19ac508: **Breaking:** Jev moves from `factbag/jev` to its own package, `@factbag/jev`. Install it alongside `factbag` and `@typesafe-ai/sdk`, which is now a required peer dependency at `^0.7.0`, and import `classifier`, `resolver`, `createConfig`, `Config`, and the `DEFAULT_*` constants from `@factbag/jev`. `factbag` no longer has a Jev entry point or an SDK peer dependency. `@factbag/jev` and `@factbag/clef` are released together with `factbag` and require the same `factbag` version.
+
+  **Breaking:** `@factbag/jev` has a single entry point. `factbag/jev/classifier`, `factbag/jev/resolve`, `factbag/jev/config`, and `factbag/jev/errors` have no replacement subpaths.
+
+  Add `batchSize` to Jev's `Config`: how many questions each request holds. It defaults to 64 and has no upper limit. An invalid `batchSize` throws when the config is created or a run is built.
+
+  Jev's `createConfig` now returns `Normalized & Config`, so `client` is no longer guaranteed on the result.
+
+- dd3730b: **Breaking:** `factbag/guards` and `factbag/query` are removed. Import `guard`, `GuardedKB`, and the other guard exports from `factbag/kb`, and `query`, `queryAll`, `Judgment`, and the goal and support types from `factbag/dsl`.
+
+## 0.0.0-alpha.4
+
+### Minor Changes
+
+- 2814aab: Allow enumerations to hold numbers or dates as well as strings, with one member
+  type per enumeration. Members must be unique; dates compare by instant and are
+  copied on construction. NaN and invalid dates are rejected. Enumeration membership
+  validation at assertion and query time is unchanged.
+- 1f5bb1b: Classify predicates whose fields are number or Date enumerations, alongside
+  string enumerations. Dates are sent to the model as ISO strings and retained as
+  `Date` values in evidence. Open-ended `String`, `Number`, and `Date` fields
+  remain unsupported.
+- 9ca1766: Reorganize classification and resolution to separate evidence workflows from model requests. The workflows own evidence admission and knowledge-base updates; the Jev implementation owns prompts, encoding, batching, and response validation.
+
+  **Breaking changes:** call the classifier with `classifier({ corpus, input, config })`. Classification and resolution jobs now expose only `execute(): Promise<void>`; read the resulting knowledge base from `run.kb`. Job metadata and assessment and resolution reports are removed. Replace `RequestConfig`, `ResolutionConfig`, and nested `AdmissionPolicy` settings with the shared, flat `Config`. Pass an SDK client directly instead of implementing the removed custom client interfaces.
+
+  Classification now executes one job per chunk across all permitted predicates. All responses for the chunk must validate before its evidence is written. Failed jobs can be retried without partial evidence, repeating the chunk's requests; successful repeats add fresh evidence.
+
+  Optionally filter candidates by passage relevance with `config: { routing: true }`. Each chunk first asks which predicates the passage may bear on. For predicates that make claims about supplied entities or values, it can also filter those symbols before combining them into complete candidate facts. `candidateProductCutoff` controls when this extra filtering runs. Filtering defaults to off: false negatives can suppress evidence, including denials, and the extra requests do not guarantee cost savings.
+
+  Expose `createConfig`, `Config`, and shared `DEFAULT_*` constants through `factbag/jev/config`. Normalize settings once and preserve a shared lazy client when a factory-created config is reused across workflows.
+
+  Export `fieldEquals` from `factbag/dsl` and use core equality in Jev: entities compare by constructor and ID, dates by instant. Resolution now groups contradictory evidence about separate instances of the same entity.
+
+  Encode candidate values when building requests, using the original entities and dates instead of construction-time JSON snapshots. Candidate domains remain fixed at run construction.
+
+## 0.0.0-alpha.3
+
+### Minor Changes
+
+- f8f2712: Add `eq` and `neq` rule-body comparisons for numbers, dates, strings, booleans, and entities. Entities compare by type and id rather than instance; dates compare by instant.
+- 900b104: Add min, max, roundTo, floorTo, and ceilTo numeric arithmetic terms for rule bodies. Rounding supports whole-number decimal places (including negative places), with halves rounded away from zero. Decimal exponent shifting avoids multiplication artifacts at decimal rounding boundaries.
+- 4f040e3: Add `daysBetween(later, earlier)` and `yearsBetween(later, earlier)` as number-valued arithmetic terms over dates. They count signed UTC calendar days and whole anniversary years, ignoring time of day; February 29 anniversaries fall on March 1 in common years. Numeric subtraction on variables now composes with other numeric operators.
+
+### Patch Changes
+
+- 01cc338: Speed up queries over large rulesets with linear-time recursive predicate grouping,
+  per-query rule and evidence indexes, and judgment reuse during candidate discovery.
+  Preserve candidate pruning and distinguish same-named predicate declarations when
+  tracking active atoms, avoiding incorrect recursion cutoffs.
+- 80d1e75: Share explanation nodes for reused proof judgments so explanation construction no longer grows with the number of paths through a shared proof. Identical sub-explanations are still listed once, and rendered content is unchanged.
+- a074dab: Judge evidence-free, closed-world recursive components together as a least fixed
+  point instead of enumerating recursive proof paths. Doubly recursive transitive
+  closures and symmetric compositions no longer require exponential proof search.
+  Other components retain the existing search semantics. Variable queries recognize
+  a non-recursive disjunctive base case within an exclusive definition.
+
+## 0.0.0-alpha.2
+
+### Major Changes
+
+- e212a94: Remove bigint support from predicate schemas, numeric expressions, aggregates, and numeric proof ranges. Numeric values now use JavaScript number exclusively, and an empty sum returns 0. The DSL rejects BigInt schemas and bigint operands rather than coercing them.
+
+  Migrate BigInt fields to Number and bigint literals to numbers. Division now uses number semantics (fractional results rather than bigint truncation); values outside the safe integer range can lose precision. Date support is unchanged.
+
+### Patch Changes
+
+- bc114ed: Add npm alpha version, CI status, and license badges to the README.
+- a3583ab: Publish the full project README on npm, including the document-to-conclusion walkthrough.
+
+## 0.0.0-alpha.1
+
+### Patch Changes
+
+- ebc4a8a: A `letIn` or aggregate whose variable is already bound now constrains that variable instead of rebinding it. Before, a rule such as `tax(P, R) iff letIn(R, ...)` concluded `tax(alice, 99)` as true when its body computed 98, and an `or` branch evaluated under another branch's bindings reported those bindings as true. Proofs for such queries now carry a temporary variable and an `eq` comparison.
+- eca65c2: An `or` is now judged per binding environment, so a branch that fails without binding a variable can no longer borrow the truth of a sibling branch whose bindings were discarded. Before, `and(or(p(X), r()), s(X))` could be judged true when `p(x1)` and `s(x3)` held but nothing satisfied both: the false `r()` branch produced an environment without `X`, the `or` was judged true there via `p(x1)`, and `s(X)` then ranged over every candidate. The recursion validator's edge collector also now carries variables bound in every `or` branch forward, matching the variable-use checker, so a comparison after such an `or` is no longer reported as unconstructive recursion.
+
+## 0.0.0-alpha.0
+
+Initial experimental distribution of core, corpus, guards, and Jev functionality.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Daniel du Plessis
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,309 @@
-# Temporary Holding Version
+# Factbag
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm alpha](https://img.shields.io/npm/v/factbag/alpha)](https://www.npmjs.com/package/factbag)
+[![CI](https://img.shields.io/github/actions/workflow/status/factbag/factbag/ci.yml?branch=main&event=push&label=CI)](https://github.com/factbag/factbag/actions/workflows/ci.yml?query=branch%3Amain)
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/factbag/factbag/blob/main/LICENSE)
+
+<img src="https://raw.githubusercontent.com/factbag/factbag/main/docs/assets/factbag.png" alt="An open canvas bag" align="right" width="180" />
+
+Turn documents into evidence and conclusions with [Jev](https://typesafe.ai/) and TypeScript.
+
+Factbag uses TypeSafe AI’s Jev model to read passages and assess specific claims.
+Those assessments become evidence in a knowledge base, alongside facts from your
+application. You write the rules that connect them and query what follows.
+
+Each piece of documentary evidence points back to its source passage. Conclusions
+can be **true**, **false**, **conflicted**, or **unknown**. When documents disagree,
+you can inspect the conflicting evidence, correct a particular fact, and query
+the rules again.
+
+> **Important:** Factbag is an early alpha release and still pretty rough - APIs will definitely change.
+
+## How it works
+
+1. **Define the claims** you want Jev to assess, with descriptions of what counts
+   as evidence.
+2. **Add documents** to a corpus and choose which predicates Jev may assert or deny.
+3. **Execute classification jobs.** Jev assesses whether each passage supports,
+   contradicts, or is irrelevant to each candidate claim.
+4. **Query the result.** Factbag combines admitted evidence with your existing
+   facts and rules, retaining the sources behind the conclusion.
+
+## Install
+
+```sh
+npm install factbag@alpha @factbag/jev@alpha @typesafe-ai/sdk@^0.7.0
+```
+
+`@factbag/jev` is released with `factbag` and needs the same version. To use
+Cloudflare's Clef models on Workers AI instead, install `@factbag/clef@alpha`, which
+does not need the TypeSafe SDK. To let an OpenAI-compatible model read and write a
+knowledge base through tool calls, install `@factbag/openai@alpha`.
+
+ESM only. Requires Node 22.18+ on the 22.x line, or Node 24 or 26.
+
+Set your TypeSafe API key in the environment:
+
+```sh
+export TYPESAFE_API_KEY="your-api-key"
+```
+
+## From a document to a conclusion
+
+### 1. Decide on your ruleset
+
+Start with the criteria your application needs to apply. These might be your own
+business rules or requirements set out in legislation or regulations.
+
+Here, we're translating the individual-income route in the SEC's
+[accredited-investor definition, 17 CFR § 230.501(a)(6)](<https://www.ecfr.gov/current/title-17/chapter-II/part-230/section-230.501#p-230.501(a)(6)>),
+into three conditions:
+
+- Individual income exceeded $200,000 in the first of the two most recent years.
+- Individual income exceeded $200,000 in the second year.
+- The person reasonably expects to reach the same income level in the current year.
+
+### 2. Define the claims
+
+Declare the facts we'll combine, and describe the claims Jev will assess.
+
+```ts
+import { enumeration, predicate } from "factbag/dsl";
+
+class Person {
+  constructor(
+    readonly id: string,
+    readonly name: string,
+  ) {}
+}
+
+const hasIncomeOver200k = predicate(
+  "has_income_over_200k",
+  { person: Person, year: enumeration(2024, 2025) },
+  {
+    description:
+      "The person's total individual annual income exceeded USD 200,000 in the " +
+      "specified year. Joint household income and forecasts do not count.",
+  },
+);
+
+const expectsSameIncome = predicate(
+  "expects_same_income",
+  { person: Person },
+  {
+    description:
+      "The person reasonably expects their individual income in 2026 to remain " +
+      "at least at the level earned in each of 2024 and 2025.",
+  },
+);
+
+const isQualifiedInvestor = predicate("is_qualified_investor", {
+  person: Person,
+});
+const hasVerifiedIdentity = predicate("has_verified_identity", {
+  person: Person,
+});
+const isReadyForReview = predicate("is_ready_for_review", { person: Person });
+```
+
+### 3. Encode the ruleset
+
+All three income conditions must hold for this route to qualification. Our
+application also requires verified identity before sending an investor for review.
+
+```ts
+import { and, variable } from "factbag/dsl";
+import { KnowledgeBase } from "factbag/kb";
+
+const person = variable("person");
+const kb = new KnowledgeBase();
+
+kb.rule(isQualifiedInvestor({ person })).if(
+  and(
+    hasIncomeOver200k({ person, year: 2024 }),
+    hasIncomeOver200k({ person, year: 2025 }),
+    expectsSameIncome({ person }),
+  ),
+);
+
+kb.rule(isReadyForReview({ person })).if(
+  and(isQualifiedInvestor({ person }), hasVerifiedIdentity({ person })),
+);
+```
+
+### 4. Import a known fact and add documents
+
+Identity verification comes directly from our onboarding system. Income evidence
+goes into the corpus for Jev to assess.
+
+```ts
+import { Corpus } from "factbag/corpus";
+
+const alice = new Person("alice", "Alice");
+kb.entities.add(alice);
+
+kb.asserts(hasVerifiedIdentity({ person: alice }), {
+  source: "onboarding:alice",
+});
+
+const corpus = new Corpus();
+
+// Tax returns provide evidence of past annual income.
+corpus.add({ documentId: "alice-2024-federal-tax-return", text: "…" });
+corpus.add({ documentId: "alice-2025-federal-tax-return", text: "…" });
+
+// An employer letter supports the expectation of continued income.
+corpus.add({
+  documentId: "alice-2026-employment-confirmation-letter",
+  text: "…",
+});
+```
+
+### 5. Set Jev's permissions
+
+The guard starts with no permissions. Permit Jev to assert or deny the two income
+predicates.
+
+```ts
+import { guard } from "factbag/kb";
+
+const incomeEvidence = guard(kb)
+  .permit("assert", hasIncomeOver200k)
+  .permit("deny", hasIncomeOver200k)
+  .permit("assert", expectsSameIncome)
+  .permit("deny", expectsSameIncome);
+```
+
+### 6. Ask Jev to assess the income evidence
+
+```ts
+import { classifier } from "@factbag/jev";
+
+const run = classifier({ corpus, input: incomeEvidence });
+
+for (const job of run) {
+  await job.execute(); // Makes a live Jev request.
+}
+```
+
+### 7. Query the conclusion
+
+The output knowledge base combines the imported fact and rules with the admitted
+evidence.
+
+```ts
+import { query } from "factbag/dsl";
+
+const qualification = query(run.kb, isQualifiedInvestor({ person: alice }));
+const reviewReadiness = query(run.kb, isReadyForReview({ person: alice }));
+
+// Both are "true" if Jev admits supporting evidence for all three income claims.
+qualification.value; // "true"
+reviewReadiness.value; // "true"
+```
+
+Results can be `true`, `false`, `conflicted`, or
+`unknown`, depending on the evidence admitted.
+
+### 8. Inspect the proof tree
+
+Use `explainJudgment()` to follow a conclusion through its rule to the supporting
+evidence and source passages.
+
+```ts
+import { explainJudgment } from "factbag/explain";
+
+const proof = explainJudgment(qualification);
+JSON.stringify(proof, null, 2); // JSON shown below.
+```
+
+An abbreviated example with supporting evidence for all three claims:
+
+```json
+{
+  "claim": "is_qualified_investor(alice) = true",
+  "because": "is_qualified_investor(person) if and(...)",
+  "given": [
+    {
+      "claim": "has_income_over_200k(alice, 2024) = true",
+      "because": {
+        "source": "alice-2024-federal-tax-return#0-1"
+      }
+    },
+    {
+      "claim": "has_income_over_200k(alice, 2025) = true",
+      "because": {
+        "source": "alice-2025-federal-tax-return#0-1"
+      }
+    },
+    {
+      "claim": "expects_same_income(alice) = true",
+      "because": {
+        "source": "alice-2026-employment-confirmation-letter#0-1"
+      }
+    }
+  ]
+}
+```
+
+Source IDs identify document passages; their ranges depend on the document text.
+Use `corpus.resolve(source)` to retrieve the passage behind a piece of evidence.
+
+```ts
+const source = "alice-2024-federal-tax-return#0-1";
+corpus.resolve(source); // Object shown below.
+```
+
+The result includes the exact passage and its containing document:
+
+```json
+{
+  "chunk": {
+    "id": "alice-2024-federal-tax-return#0-1",
+    "documentId": "alice-2024-federal-tax-return",
+    "range": { "start": 0, "end": 1 },
+    "text": "…"
+  },
+  "document": {
+    "documentId": "alice-2024-federal-tax-return",
+    "text": "…",
+    "metadata": {}
+  }
+}
+```
+
+### 9. Review conflicting evidence (optional)
+
+Suppose an original tax return puts Alice below the income threshold, but an
+amended return puts her above it. Jev admits both accounts, leaving qualification
+`conflicted`. In this example, the other income conditions have supporting evidence.
+
+You could pass the conflicting evidence to a human for review, or ask Jev to
+compare the sources using the `resolver`.
+
+Evidence judged superseded is retracted from the resolver's output
+knowledge base.
+
+```ts
+import { resolver } from "@factbag/jev";
+
+query(run.kb, isQualifiedInvestor({ person: alice })).value; // "conflicted"
+
+const review = resolver(corpus, run.kb);
+
+for (const job of review) {
+  await job.execute();
+}
+
+// If the resolver retracts the superseded return's denial:
+query(review.kb, isQualifiedInvestor({ person: alice })).value; // "true"
+```
+
+## Go further
+
+- [Introducing Factbag](https://daniel.du-pless.is/introducing-factbag): how and why
+  to use it.
+- [Jev and the Art of Truth Maintenance](https://daniel.du-pless.is/jev-and-the-art-of-truth-maintenance):
+  the thinking behind the project.
+
+Apache-2.0 licensed.