factbag 0.0.0-alpha.0 → 0.0.0-alpha.2

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # factbag
 
+## 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/README.md

@@ -1,44 +1,306 @@
 # Factbag
 
-A TypeScript library for combining evidence with explicit rules in a knowledgebase.
-Facts can be true, false, conflicted, or unknown. Query results keep track of the
-sources and rules behind a conclusion.
+[![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)
 
-Factbag includes a document corpus, permission controls, and an integration with
-TypeSafe AI’s Jev model.
+<img src="https://raw.githubusercontent.com/factbag/factbag/main/docs/assets/factbag.png" alt="An open canvas bag" align="right" width="180" />
 
-Read [Introducing Factbag](https://blog.du-pless.is/introducing-factbag) for how and
-why to use it, or [Jev and the Art of Truth Maintenance](https://blog.du-pless.is/jev-and-the-art-of-truth-maintenance)
-for the thinking behind it.
+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
+npm install factbag@alpha @typesafe-ai/sdk@^0.6.0
 ```
 
 ESM only. Requires Node 22.18+ on the 22.x line, or Node 24 or 26.
-This is an early prerelease; APIs may change.
 
-## Example
+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 { predicate, variable } from "factbag/dsl";
+import { and, enumeration, predicate, variable } from "factbag/dsl";
 import { KnowledgeBase } from "factbag/kb";
 import { query } from "factbag/query";
+import { Corpus } from "factbag/corpus";
+import { guard } from "factbag/guards";
+import { classifier } from "factbag/jev/classifier";
+
+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 });
+```
 
-const emailVerified = predicate("email_verified", { user: String });
-const canSignIn = predicate("can_sign_in", { user: String });
-const user = variable("user");
+### 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
+const person = variable("person");
 const kb = new KnowledgeBase();
 
-kb.rule(canSignIn({ user })).if(emailVerified({ user }));
-kb.asserts(emailVerified({ user: "alice" }), { source: "accounts" });
+kb.rule(isQualifiedInvestor({ person })).if(
+  and(
+    hasIncomeOver200k({ person, year: "2024" }),
+    hasIncomeOver200k({ person, year: "2025" }),
+    expectsSameIncome({ person }),
+  ),
+);
 
-query(kb, canSignIn({ user: "alice" })).value; // "true"
+kb.rule(isReadyForReview({ person })).if(
+  and(isQualifiedInvestor({ person }), hasVerifiedIdentity({ person })),
+);
 ```
 
-For Jev, also install `@typesafe-ai/sdk@^0.6.0`. Other parts of Factbag do not
-require it. Live Jev requests need a TypeSafe API key.
+### 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
+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
+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
+const run = classifier(corpus, 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
+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(...), with person = alice",
+  "given": [
+    {
+      "claim": "and(...) = true",
+      "given": [
+        {
+          "claim": "has_income_over_200k(alice, 2024) = true",
+          "because": {
+            "claim": "has_income_over_200k(alice, 2024) = true",
+            "source": "alice-2024-federal-tax-return#0-1"
+          }
+        },
+        {
+          "claim": "has_income_over_200k(alice, 2025) = true",
+          "because": {
+            "claim": "has_income_over_200k(alice, 2025) = true",
+            "source": "alice-2025-federal-tax-return#0-1"
+          }
+        },
+        {
+          "claim": "expects_same_income(alice) = true",
+          "because": {
+            "claim": "expects_same_income(alice) = true",
+            "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/resolve";
+
+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.

package/dist/core/{chunk-4IP7CXNV.js → chunk-5J3WGMN2.js}

@@ -50,7 +50,7 @@ function fieldIdentityToken(value) {
     return ["entity", value.constructor.name, value.id];
   }
   if (typeof value === "bigint") {
-    return ["bigint", value.toString()];
+    throw new TypeError("bigint is not supported; use number values");
   }
   return value;
 }

package/dist/core/dsl/assert-supported-value.d.ts

@@ -0,0 +1,2 @@
+/** Reject removed scalar types before building rules or atoms. */
+export declare function assertSupportedValue(value: unknown): void;

package/dist/core/dsl/index.js

@@ -1,11 +1,18 @@
 import {
   assertAtomLike,
   assertGroundAtom
-} from "../chunk-4IP7CXNV.js";
+} from "../chunk-5J3WGMN2.js";
 import {
   Var
 } from "../chunk-UVOCOH2I.js";
 
+// src/dsl/assert-supported-value.ts
+function assertSupportedValue(value) {
+  if (typeof value === "bigint" || value === BigInt) {
+    throw new TypeError("bigint is not supported; use number values and Number fields");
+  }
+}
+
 // src/dsl/formula.ts
 function not(atom) {
   return { sign: "-", atom };
@@ -20,6 +27,7 @@ function exists(...args) {
   return { kind: "exists", args };
 }
 function letIn(variable2, value, body) {
+  assertSupportedValue(value);
   return { kind: "letIn", args: [variable2, value, body] };
 }
 
@@ -31,6 +39,7 @@ function count(value) {
   return aggregateBuilder("count", value);
 }
 function aggregateBuilder(kind, value) {
+  assertSupportedValue(value);
   const where = (body, options) => ({
     kind,
     args: options === void 0 ? [value, body] : [value, body, options]
@@ -40,37 +49,53 @@ function aggregateBuilder(kind, value) {
 
 // src/dsl/operators/arithmetic.ts
 function add(left, right) {
+  assertSupportedValue(left);
+  assertSupportedValue(right);
   return { kind: "add", args: [left, right] };
 }
 function sub(left, right) {
+  assertSupportedValue(left);
+  assertSupportedValue(right);
   return { kind: "sub", args: [left, right] };
 }
 function mul(left, right) {
+  assertSupportedValue(left);
+  assertSupportedValue(right);
   return { kind: "mul", args: [left, right] };
 }
 function div(left, right) {
+  assertSupportedValue(left);
+  assertSupportedValue(right);
   return { kind: "div", args: [left, right] };
 }
 
 // src/dsl/operators/comparison.ts
 function gt(left, right) {
+  assertSupportedValue(left);
+  assertSupportedValue(right);
   return { kind: "gt", args: [left, right] };
 }
 function gte(left, right) {
+  assertSupportedValue(left);
+  assertSupportedValue(right);
   return { kind: "gte", args: [left, right] };
 }
 function lte(left, right) {
+  assertSupportedValue(left);
+  assertSupportedValue(right);
   return { kind: "lte", args: [left, right] };
 }
 
 // src/dsl/predicate.ts
 function makePredicate(name, params, world, metadata) {
+  Object.values(params).forEach(assertSupportedValue);
   const holder = {};
   const construct = (fields) => {
     const current = holder.current;
     if (current === void 0) {
       throw new Error(`Predicate ${name} was called before initialization`);
     }
+    Object.values(fields).forEach(assertSupportedValue);
     return { predicate: current, fields };
   };
   const declared = construct;

package/dist/core/dsl/operators/aggregate.d.ts

@@ -21,7 +21,7 @@ import type { AggregateBuilder, NumericTerm, Term } from "../types.js";
  * );
  * ```
  */
-export declare function sum(value: NumericTerm): AggregateBuilder<number | bigint>;
+export declare function sum(value: NumericTerm): AggregateBuilder;
 /**
  * Count the rows matched by the aggregate body. Runs through the same
  * aggregate machinery as {@link sum}, but thresholds the number of matching

package/dist/core/dsl/operators/arithmetic.d.ts

@@ -1,6 +1,6 @@
 import type { DateTerm, Formula, NumericTerm } from "../types.js";
 /** Add two numeric terms, producing a numeric rule-body expression. */
-export declare function add(left: NumericTerm, right: NumericTerm): Formula<number | bigint, readonly [NumericTerm, NumericTerm]>;
+export declare function add(left: NumericTerm, right: NumericTerm): Formula<number, readonly [NumericTerm, NumericTerm]>;
 /**
  * Subtract a numeric duration in milliseconds from a date term, producing a
  * date expression.
@@ -20,8 +20,8 @@ export declare function add(left: NumericTerm, right: NumericTerm): Formula<numb
  */
 export declare function sub(left: DateTerm, right: NumericTerm): Formula<Date, readonly [DateTerm, NumericTerm]>;
 /** Subtract one numeric term from another. */
-export declare function sub(left: NumericTerm, right: NumericTerm): Formula<number | bigint, readonly [NumericTerm, NumericTerm]>;
+export declare function sub(left: NumericTerm, right: NumericTerm): Formula<number, readonly [NumericTerm, NumericTerm]>;
 /** Multiply two numeric terms, producing a numeric rule-body expression. */
-export declare function mul(left: NumericTerm, right: NumericTerm): Formula<number | bigint, readonly [NumericTerm, NumericTerm]>;
+export declare function mul(left: NumericTerm, right: NumericTerm): Formula<number, readonly [NumericTerm, NumericTerm]>;
 /** Divide one numeric term by another, producing a numeric rule-body expression. */
-export declare function div(left: NumericTerm, right: NumericTerm): Formula<number | bigint, readonly [NumericTerm, NumericTerm]>;
+export declare function div(left: NumericTerm, right: NumericTerm): Formula<number, readonly [NumericTerm, NumericTerm]>;

package/dist/core/dsl/types.d.ts

@@ -7,7 +7,7 @@ export type { Entity };
 /** Predicate over stored literal handles. */
 export type LiteralFilter = (literal: AnyLiteral) => boolean;
 /** A scalar value accepted in example expressions. */
-export type Scalar = string | number | bigint | boolean | Date;
+export type Scalar = string | number | boolean | Date;
 /** A concrete value or logic variable used in formulas and examples. */
 export type Term<Value = Scalar | Entity> = Value | Var;
 /**
@@ -39,13 +39,13 @@ export type LiteralArgs<Args extends readonly unknown[]> = {
     readonly [Index in keyof Args]: LiteralInput<Args[Index]>;
 };
 /** Numeric term accepted by arithmetic, comparisons, and aggregate helpers. */
-export type NumericTerm = number | bigint | Var | Formula<number | bigint, readonly unknown[]>;
+export type NumericTerm = number | Var | Formula<number, readonly unknown[]>;
 /** Date term accepted by date comparisons and date-offset arithmetic. */
 export type DateTerm = Date | Var | Formula<Date, readonly unknown[]>;
 /** Term accepted by comparison helpers. */
 export type ComparableTerm = NumericTerm | DateTerm;
 /** Aggregate builder returned by sum(...) and count(...). */
-export type AggregateBuilder<Value extends number | bigint = number> = Readonly<{
+export type AggregateBuilder<Value extends number = number> = Readonly<{
     where: (<const Body>(body: Body & RuleBodyInput<Body>) => Formula<Value, readonly [Body]>) & (<const Body, const CompleteWhen>(body: Body & RuleBodyInput<Body>, options: Readonly<{
         completeWhen: CompleteWhen & RuleBodyInput<CompleteWhen>;
     }>) => Formula<Value, readonly [Body, Readonly<{

package/dist/core/explanation/index.js

@@ -1,6 +1,6 @@
 import {
   isFormula
-} from "../chunk-YF4PP42K.js";
+} from "../chunk-A6ZZJWIO.js";
 import {
   AssertionError,
   isVar

package/dist/core/knowledge-base/index.js

@@ -6,7 +6,7 @@ import {
 } from "../chunk-X3LSDJL4.js";
 import {
   isAtomLike
-} from "../chunk-4IP7CXNV.js";
+} from "../chunk-5J3WGMN2.js";
 import "../chunk-UVOCOH2I.js";
 
 // src/knowledge-base/assertions/exclusive-definitions.ts

package/dist/core/query/index.js

@@ -1,6 +1,6 @@
 import {
   isFormula
-} from "../chunk-YF4PP42K.js";
+} from "../chunk-A6ZZJWIO.js";
 import {
   PrimitiveArithmeticProgrammerError,
   UnconstructiveRecursionProgrammerError,
@@ -14,7 +14,7 @@ import {
   isAtomForPredicate,
   isAtomLike,
   isGroundAtom
-} from "../chunk-4IP7CXNV.js";
+} from "../chunk-5J3WGMN2.js";
 import {
   AssertionError,
   Var,
@@ -79,6 +79,15 @@ function uniqueVariables(variables) {
   }
   return unique;
 }
+function bindingsAfterOr(branchBindings, bound) {
+  const next = new Set(bound);
+  for (const candidate of uniqueVariables(branchBindings.flatMap((branch) => [...branch]))) {
+    if (branchBindings.every((branch) => branch.has(candidate))) {
+      next.add(candidate);
+    }
+  }
+  return next;
+}
 function variablesIn(value) {
   if (isVar(value)) {
     return [value];
@@ -95,7 +104,7 @@ function collectBodyEdges(body, headPredicate, bound, edges) {
   if (isAtomLike(body)) {
     edges.push({ from: headPredicate, to: body.predicate, kind: "positive" });
     bindVariables(body, bound);
-    return;
+    return bound;
   }
   if (isNegativeLiteral(body)) {
     edges.push({
@@ -103,20 +112,26 @@ function collectBodyEdges(body, headPredicate, bound, edges) {
       to: body.atom.predicate,
       kind: body.atom.predicate.world === "closed" ? "closed-world-not" : "explicit-not"
     });
-    bindVariables(body.atom, bound);
-    return;
+    return bound;
   }
   if (isFormula(body, "and")) {
+    let nextBound = bound;
     for (const arg of body.args) {
-      collectBodyEdges(arg, headPredicate, bound, edges);
+      nextBound = collectBodyEdges(arg, headPredicate, nextBound, edges);
     }
-    return;
+    return nextBound;
+  }
+  if (isFormula(body, "or")) {
+    const branchBindings = body.args.map(
+      (arg) => collectBodyEdges(arg, headPredicate, new Set(bound), edges)
+    );
+    return bindingsAfterOr(branchBindings, bound);
   }
-  if (isFormula(body, "or") || isFormula(body, "exists")) {
+  if (isFormula(body, "exists")) {
     for (const arg of body.args) {
       collectBodyEdges(arg, headPredicate, new Set(bound), edges);
     }
-    return;
+    return bound;
   }
   if (isFormula(body, "letIn")) {
     const [variable, value, nextBody] = body.args;
@@ -128,12 +143,12 @@ function collectBodyEdges(body, headPredicate, bound, edges) {
     if (isVar(variable)) {
       bound.add(variable);
     }
-    collectBodyEdges(nextBody, headPredicate, bound, edges);
-    return;
+    return collectBodyEdges(nextBody, headPredicate, bound, edges);
   }
   if (isPrimitiveFormula(body) && hasUnboundVariable(body, bound)) {
     edges.push({ from: headPredicate, to: headPredicate, kind: "primitive-ungrounded" });
   }
+  return bound;
 }
 function collectAggregateEdges(aggregate, headPredicate, bound, edges) {
   for (const arg of aggregate.args.slice(1)) {
@@ -252,7 +267,10 @@ function assertSafeBody(body, bound) {
     return nextBound;
   }
   if (isFormula(body, "or")) {
-    return bindingsAvailableAfterOr(body.args, bound);
+    return bindingsAfterOr(
+      body.args.map((arg) => assertSafeBody(arg, new Set(bound))),
+      bound
+    );
   }
   if (isFormula(body, "exists")) {
     const nextBody = body.args.at(-1);
@@ -288,16 +306,6 @@ function assertSafeAggregate(aggregate, bound) {
     assertSafeBody(options.completeWhen, new Set(bound));
   }
 }
-function bindingsAvailableAfterOr(args, bound) {
-  const branchBindings = args.map((arg) => assertSafeBody(arg, new Set(bound)));
-  const next = new Set(bound);
-  for (const candidate of uniqueVariables(branchBindings.flatMap((branch) => [...branch]))) {
-    if (branchBindings.length > 0 && branchBindings.every((branch) => branch.has(candidate))) {
-      next.add(candidate);
-    }
-  }
-  return next;
-}
 function assertVariablesBound(variables, bound) {
   const unbound = uniqueVariables(variables).filter((variable) => !bound.has(variable));
   if (unbound.length > 0) {
@@ -727,7 +735,15 @@ function assertNever(value, message) {
 }
 function evaluateRuleBodyMany(literals, rules, body, bindings, active, context, pathCanHaveUnavailableBindings = false) {
   if (isAtomLike(body)) {
-    return evaluateAtomBody(literals, rules, erasedAtom(body), bindings, active, context);
+    return evaluateAtomBody(
+      literals,
+      rules,
+      erasedAtom(body),
+      bindings,
+      active,
+      context,
+      pathCanHaveUnavailableBindings
+    );
   }
   if (isLiteralLike(body) && body.sign === "-") {
     const bodyAtom = erasedAtom(body.atom);
@@ -907,9 +923,13 @@ function evaluateOrBody(literals, rules, args, bindings, active, context, pathCa
     )
   );
   const environments = candidateBindings.length === 0 ? [bindings] : candidateBindings;
-  return environments.map((environment) => {
-    const judgments = args.map((arg) => {
-      const results = evaluateRuleBodyMany(
+  const queue = [...environments];
+  const seen = new Set(queue.map(bindingsKey));
+  const results = [];
+  for (let next = queue.shift(); next !== void 0; next = queue.shift()) {
+    const environment = next;
+    const judgments = args.flatMap((arg) => {
+      const branch = evaluateRuleBodyMany(
         literals,
         rules,
         arg,
@@ -918,15 +938,27 @@ function evaluateOrBody(literals, rules, args, bindings, active, context, pathCa
         context,
         pathCanHaveUnavailableBindings
       );
-      assert(results.length > 0, "Or branch evaluation produced no results");
-      const result = bestResult(results);
-      assert(result !== void 0, "Or branch evaluation produced no best result");
-      return result.judgment;
+      for (const result2 of branch) {
+        if (bindsBeyond(result2.bindings, environment)) {
+          const key = bindingsKey(result2.bindings);
+          if (!seen.has(key)) {
+            seen.add(key);
+            queue.push(result2.bindings);
+          }
+        }
+      }
+      const result = bestResult(
+        branch.filter((candidate) => !bindsBeyond(candidate.bindings, environment))
+      );
+      return result === void 0 ? [] : [result.judgment];
     });
+    if (judgments.length === 0) {
+      continue;
+    }
     const judgmentBindings = bindingsArray(environment);
     const reboundJudgments = judgments.map((judgment) => withBindings(judgment, judgmentBindings));
     const goal = { kind: "or", goals: reboundJudgments.map((judgment) => judgment.goal) };
-    return {
+    results.push({
       judgment: compoundJudgment(
         goal,
         maxGoalValue(...reboundJudgments.map((judgment) => judgment.value)),
@@ -934,8 +966,9 @@ function evaluateOrBody(literals, rules, args, bindings, active, context, pathCa
         reboundJudgments
       ),
       bindings: environment
-    };
-  });
+    });
+  }
+  return results;
 }
 function evaluateAndBody(literals, rules, args, bindings, active, context, pathCanHaveUnavailableBindings) {
   let partials = [{ bindings, judgments: [] }];
@@ -976,7 +1009,7 @@ function evaluateAndBody(literals, rules, args, bindings, active, context, pathC
     };
   });
 }
-function evaluateAtomBody(literals, rules, atom, bindings, active, context) {
+function evaluateAtomBody(literals, rules, atom, bindings, active, context, pathCanHaveUnavailableBindings = false) {
   const evaluateGrounded = (environment) => {
     const grounded = groundAtom(atom, environment);
     const judgmentBindings = bindingsArray(environment);
@@ -998,7 +1031,14 @@ function evaluateAtomBody(literals, rules, atom, bindings, active, context) {
       ])
     )
   };
-  const candidateBindings = candidateGroundAtoms(literals, rules, pattern, active, context.search).map((candidate) => extendBindings(atom, candidate, bindings)).filter((candidate) => candidate !== void 0);
+  const candidateBindings = candidateGroundAtoms(
+    literals,
+    rules,
+    pattern,
+    active,
+    context.search,
+    pathCanHaveUnavailableBindings
+  ).map((candidate) => extendBindings(atom, candidate, bindings)).filter((candidate) => candidate !== void 0);
   if (candidateBindings.length === 0) {
     if (atom.predicate.world === "closed") {
       assert(!canGroundAtom(atom, bindings), "Ground closed-world absence must use ground solving");
@@ -1156,16 +1196,16 @@ function definedValue(value, message) {
   return value;
 }
 function isDefinedValue(value) {
-  return typeof value === "string" || typeof value === "number" || typeof value === "bigint" || typeof value === "boolean" || typeof value === "object" && value !== null;
+  return typeof value === "string" || typeof value === "number" || typeof value === "boolean" || typeof value === "object" && value !== null;
 }
 function isGoalExpression(value) {
-  return isVar(value) || typeof value === "string" || typeof value === "number" || typeof value === "bigint" || typeof value === "boolean" || value instanceof Date || typeof value === "object" && value !== null && "id" in value && typeof value.id === "string";
+  return isVar(value) || typeof value === "string" || typeof value === "number" || typeof value === "boolean" || value instanceof Date || typeof value === "object" && value !== null && "id" in value && typeof value.id === "string";
 }
 function isScalarGoalExpression(value) {
-  return isVar(value) || typeof value === "string" || typeof value === "number" || typeof value === "bigint" || typeof value === "boolean" || value instanceof Date;
+  return isVar(value) || typeof value === "string" || typeof value === "number" || typeof value === "boolean" || value instanceof Date;
 }
 function isNumericGoalExpression(value) {
-  return isVar(value) || typeof value === "number" || typeof value === "bigint";
+  return isVar(value) || typeof value === "number";
 }
 function evaluateExpression(expression, bindings, context) {
   if (isVar(expression)) {
@@ -1181,7 +1221,7 @@ function evaluateExpression(expression, bindings, context) {
     const right = evaluateExpression(expression.args[1], left.bindings, context);
     assert(isScalarGoalExpression(left.expression), "Left arithmetic operand must be scalar");
     assert(isScalarGoalExpression(right.expression), "Right arithmetic operand must be scalar");
-    const variable = new Var(`$tmp${context.nextTemp++}`);
+    const variable = new Var(`${TEMPORARY_PREFIX}${context.nextTemp++}`);
     const goal = {
       kind: expression.kind,
       bind: variable,
@@ -1220,6 +1260,10 @@ function evaluateExpression(expression, bindings, context) {
   };
 }
 function evaluateExpressionInto(variable, expression, bindings, context) {
+  const existing = valueForVariable(bindings, variable);
+  if (existing !== UNBOUND) {
+    return constrainBoundVariable(variable, existing, expression, bindings, context);
+  }
   if (isArithmeticFormula(expression)) {
     const left = evaluateExpression(expression.args[0], bindings, context);
     const right = evaluateExpression(expression.args[1], left.bindings, context);
@@ -1256,9 +1300,35 @@ function evaluateExpressionInto(variable, expression, bindings, context) {
   }
   const value = isVar(expression) ? valueForVariable(bindings, expression) : definedValue(expression, "Expression values must be defined");
   const nextBindings = new Map(bindings);
-  nextBindings.set(variable, value);
+  if (value !== UNBOUND) {
+    nextBindings.set(variable, value);
+  }
   return { value, expression: variable, bindings: nextBindings, judgments: [] };
 }
+function constrainBoundVariable(variable, existing, expression, bindings, context) {
+  const computed = evaluateExpression(expression, bindings, context);
+  assert(
+    isScalarGoalExpression(computed.expression),
+    "A let binding of a bound variable must compare scalar values"
+  );
+  const goal = { kind: "eq", left: variable, right: computed.expression };
+  const value = computed.value === UNBOUND ? "unknown" : compareValues("eq", existing, computed.value);
+  const comparison = primitiveComparisonJudgment(
+    goal,
+    value,
+    bindingsArray(computed.bindings),
+    existing,
+    variable,
+    computed.value,
+    computed.expression
+  );
+  return {
+    value: existing,
+    expression: variable,
+    bindings: computed.bindings,
+    judgments: [...computed.judgments, comparison]
+  };
+}
 function evaluateAggregateInto(literals, rules, variable, aggregate, bindings, active, context) {
   const [valueExpression, whereBody, options] = aggregate.args;
   const completeWhen = options?.completeWhen;
@@ -1282,11 +1352,11 @@ function evaluateAggregateInto(literals, rules, variable, aggregate, bindings, a
     assert(completeness !== void 0, "Aggregate completeness evaluation produced no best result");
     if (completeness.judgment.value !== "true") {
       const judgmentBindings = bindingsArray(bindings);
-      let goal;
+      let goal2;
       switch (aggregate.kind) {
         case "sum":
           assert(isNumericGoalExpression(valueExpression), "Sum value must be numeric");
-          goal = {
+          goal2 = {
             kind: "sum",
             bind: variable,
             value: valueExpression,
@@ -1295,7 +1365,7 @@ function evaluateAggregateInto(literals, rules, variable, aggregate, bindings, a
           };
           break;
         case "count":
-          goal = {
+          goal2 = {
             kind: "count",
             bind: variable,
             where: whereGoal,
@@ -1308,12 +1378,14 @@ function evaluateAggregateInto(literals, rules, variable, aggregate, bindings, a
       return {
         kind: "incomplete",
         result: {
-          judgment: { value: "unknown", goal, bindings: judgmentBindings },
+          judgment: { value: "unknown", goal: goal2, bindings: judgmentBindings },
           bindings
         }
       };
     }
   }
+  const existing = valueForVariable(bindings, variable);
+  const target = existing === UNBOUND ? variable : new Var(`$tmp${context.nextTemp++}`);
   const nextBindings = new Map(bindings);
   const values = rows.map((row) => resolveAggregateValue(valueExpression, row.bindings));
   let value;
@@ -1322,29 +1394,29 @@ function evaluateAggregateInto(literals, rules, variable, aggregate, bindings, a
     case "sum":
       assert(isNumericGoalExpression(valueExpression), "Sum value must be numeric");
       value = sumValues(values);
-      nextBindings.set(variable, value);
+      nextBindings.set(target, value);
       judgment = primitiveSumJudgment(
         {
           kind: "sum",
-          bind: variable,
+          bind: target,
           value: valueExpression,
           where: whereGoal
         },
         bindingsArray(nextBindings),
         values,
-        variable,
+        target,
         value
       );
       break;
     case "count": {
       const range = countRange(possibleRows, isOpenAggregate(whereBody));
       value = exactCountValue(range);
-      nextBindings.set(variable, value);
+      nextBindings.set(target, value);
       judgment = primitiveCountJudgment(
-        { kind: "count", bind: variable, where: whereGoal },
+        { kind: "count", bind: target, where: whereGoal },
         bindingsArray(nextBindings),
         range,
-        variable,
+        target,
         value
       );
       break;
@@ -1352,9 +1424,30 @@ function evaluateAggregateInto(literals, rules, variable, aggregate, bindings, a
     default:
       return assertNever(aggregate.kind, "Unhandled aggregate kind");
   }
+  if (existing === UNBOUND) {
+    return {
+      kind: "complete",
+      expression: { value, expression: variable, bindings: nextBindings, judgments: [judgment] }
+    };
+  }
+  const goal = { kind: "eq", left: variable, right: target };
+  const comparison = primitiveComparisonJudgment(
+    goal,
+    compareValues("eq", existing, value),
+    bindingsArray(nextBindings),
+    existing,
+    variable,
+    value,
+    target
+  );
   return {
     kind: "complete",
-    expression: { value, expression: variable, bindings: nextBindings, judgments: [judgment] }
+    expression: {
+      value: existing,
+      expression: variable,
+      bindings: nextBindings,
+      judgments: [judgment, comparison]
+    }
   };
 }
 function resolveAggregateValue(expression, bindings) {
@@ -1369,10 +1462,10 @@ function aggregateValueIsAvailable(expression, bindings) {
   return valueForVariable(bindings, expression) !== UNBOUND;
 }
 function sumValues(values) {
-  if (values.every((value) => typeof value === "bigint")) {
-    return values.reduce((total, value) => total + value, 0n);
-  }
-  return values.reduce((total, value) => total + Number(value), 0);
+  return values.reduce((total, value) => {
+    assert(typeof value === "number", "Sum values must be numbers");
+    return total + value;
+  }, 0);
 }
 function aggregateWhereGoal(judgments) {
   if (judgments.length === 1) {
@@ -1546,7 +1639,7 @@ function primitiveUncertaintyForComparison(value, left, leftExpression, right, r
   return {};
 }
 function primitiveRangeForExact(value) {
-  if (typeof value !== "number" && typeof value !== "bigint") {
+  if (typeof value !== "number") {
     return {};
   }
   return { range: { lower: value, upper: value } };
@@ -1596,20 +1689,6 @@ function calculateValue(kind, left, right, goal) {
         return assertNever(kind, "Unhandled arithmetic kind");
     }
   }
-  if (typeof left === "bigint" && typeof right === "bigint") {
-    switch (kind) {
-      case "add":
-        return left + right;
-      case "sub":
-        return left - right;
-      case "mul":
-        return left * right;
-      case "div":
-        return left / right;
-      default:
-        return assertNever(kind, "Unhandled arithmetic kind");
-    }
-  }
   throw new PrimitiveArithmeticProgrammerError(kind, [left, right], goal);
 }
 function compareValues(kind, left, right) {
@@ -1637,10 +1716,7 @@ function compareValues(kind, left, right) {
   }
 }
 function compareOrderedValues(kind, left, right) {
-  assert(
-    (typeof left === "number" || typeof left === "bigint") && (typeof right === "number" || typeof right === "bigint"),
-    "Values must be comparable"
-  );
+  assert(typeof left === "number" && typeof right === "number", "Values must be comparable");
   switch (kind) {
     case "lt":
       return left < right ? "true" : "false";
@@ -1810,13 +1886,28 @@ function ruleContribution(kind, value) {
 function bindingsArray(bindings) {
   return [...bindings.entries()];
 }
+var TEMPORARY_PREFIX = "$tmp";
+function isTemporary(variable) {
+  return variable.name.startsWith(TEMPORARY_PREFIX);
+}
+function bindsBeyond(result, environment) {
+  for (const variable of result.keys()) {
+    if (!isTemporary(variable) && !environment.has(variable)) {
+      return true;
+    }
+  }
+  return false;
+}
+function bindingsKey(binding) {
+  return JSON.stringify(
+    bindingsArray(binding).filter(([variable]) => !isTemporary(variable)).map(([variable, value]) => [variable.name, fieldIdentityToken(value)])
+  );
+}
 function uniqueBindings(bindings) {
   const seen = /* @__PURE__ */ new Set();
   const unique = [];
   for (const binding of bindings) {
-    const key = JSON.stringify(
-      bindingsArray(binding).map(([variable, value]) => [variable.name, fieldIdentityToken(value)])
-    );
+    const key = bindingsKey(binding);
     if (!seen.has(key)) {
       seen.add(key);
       unique.push(binding);
@@ -1831,16 +1922,16 @@ function groundAtomKey(atom) {
   const fields = atom.predicate.paramNames.map((name) => fieldIdentityToken(atom.fields[name]));
   return `${atom.predicate.name}:${JSON.stringify(fields)}`;
 }
-function candidateGroundAtoms(literals, rules, atom, active, search) {
+function candidateGroundAtoms(literals, rules, atom, active, search, pathCanHaveUnavailableBindings = false) {
   return search.candidates.candidates(
     atom,
     matchingGroundAtoms(literals, atom),
-    () => deriveCandidateAtoms(literals, rules, atom, active, search)
+    () => deriveCandidateAtoms(literals, rules, atom, active, search, pathCanHaveUnavailableBindings)
   ).filter(
     (candidate) => isAtomForPredicate(candidate, atom.predicate)
   );
 }
-function deriveCandidateAtoms(literals, rules, atom, active, search) {
+function deriveCandidateAtoms(literals, rules, atom, active, search, pathCanHaveUnavailableBindings = false) {
   const atoms = [];
   for (const rule of rules) {
     const ruleHead = atomForPredicate(rule.head.atom, atom.predicate);
@@ -1852,9 +1943,17 @@ function deriveCandidateAtoms(literals, rules, atom, active, search) {
       continue;
     }
     const context = { nextTemp: 0, search, candidatePredicate: atom.predicate };
-    const bodies = evaluateRuleBodyMany(literals, rules, rule.body, bindings, active, context);
+    const bodies = evaluateRuleBodyMany(
+      literals,
+      rules,
+      rule.body,
+      bindings,
+      active,
+      context,
+      pathCanHaveUnavailableBindings
+    );
     for (const body of bodies) {
-      if (!canGroundAtom(ruleHead, body.bindings)) {
+      if (body.judgment.value === "false" || !canGroundAtom(ruleHead, body.bindings)) {
         continue;
       }
       const candidate = groundAtom(ruleHead, body.bindings);

package/dist/core/solver/query-validation/utils.d.ts

@@ -23,5 +23,7 @@ export declare function isCompleteWhenOption(value: unknown): value is Readonly<
 export declare function isPrimitiveFormula(value: unknown): boolean;
 export declare function bindVariables(value: unknown, bound: Set<Var>): void;
 export declare function uniqueVariables(variables: readonly Var[]): Var[];
+/** Bindings available after an `or`: those held before it plus those every branch makes. */
+export declare function bindingsAfterOr(branchBindings: readonly ReadonlySet<Var>[], bound: ReadonlySet<Var>): Set<Var>;
 export declare function variablesIn(value: unknown): Var[];
 export {};

package/dist/core/types/goal.d.ts

@@ -84,7 +84,7 @@ export type ComparisonGoal<Kind extends "eq" | "neq" | "lt" | "lte" | "gt" | "gt
 export type SumGoal = Readonly<{
     readonly kind: "sum";
     readonly bind: Var;
-    readonly value: GoalExpression<number | bigint>;
+    readonly value: GoalExpression<number>;
     readonly where: Goal;
     readonly completeWhen?: Goal;
 }>;

package/dist/core/types/judgment.d.ts

@@ -56,8 +56,8 @@ export type PrimitiveEvaluation = Readonly<{
 }>;
 /** Numeric lower/upper bound produced or consumed by a primitive operation. */
 export type NumericRange = Readonly<{
-    readonly lower: number | bigint;
-    readonly upper: number | bigint | "infinity";
+    readonly lower: number;
+    readonly upper: number | "infinity";
 }>;
 /** Why a primitive evaluation is not exact. */
 export type PrimitiveUncertainty = Readonly<{

package/dist/core/types/schema.d.ts

@@ -17,9 +17,9 @@ export type RuntimeConstructor<T> = (abstract new (...args: never[]) => T) & Rea
     name: string;
 }>;
 /** Any runtime validator accepted in a predicate schema field. */
-export type RuntimeType<T> = EnumType | RuntimeConstructor<T & Entity> | BigIntConstructor | BooleanConstructor | DateConstructor | NumberConstructor | StringConstructor;
+export type RuntimeType<T> = EnumType | RuntimeConstructor<T & Entity> | BooleanConstructor | DateConstructor | NumberConstructor | StringConstructor;
 /** A predicate schema maps field names to runtime validators/constructors. */
-export type PredicateSchema = Readonly<Record<string, BigIntConstructor | BooleanConstructor | DateConstructor | NumberConstructor | StringConstructor | EnumType | ((abstract new (...args: never[]) => Entity) & Readonly<{
+export type PredicateSchema = Readonly<Record<string, BooleanConstructor | DateConstructor | NumberConstructor | StringConstructor | EnumType | ((abstract new (...args: never[]) => Entity) & Readonly<{
     prototype: Entity;
     name: string;
 }>)>>;
@@ -28,6 +28,6 @@ export type PredicateSchema = Readonly<Record<string, BigIntConstructor | Boolea
  * type. A schema-erased constructor (the bare `RuntimeConstructor<Entity>`)
  * infers `unknown`, so erased atoms keep permissive field types.
  */
-export type InferRuntime<T> = T extends EnumType<infer Value> ? Value : T extends StringConstructor ? string : T extends NumberConstructor ? number : T extends BooleanConstructor ? boolean : T extends BigIntConstructor ? bigint : T extends DateConstructor ? Date : T extends {
+export type InferRuntime<T> = T extends EnumType<infer Value> ? Value : T extends StringConstructor ? string : T extends NumberConstructor ? number : T extends BooleanConstructor ? boolean : T extends DateConstructor ? Date : T extends {
     prototype: infer Value;
 } ? RuntimeConstructor<Entity> extends T ? unknown : Value : never;

package/dist/jev/{chunk-2UXHML67.js → chunk-PISXBJOT.js}

@@ -65,8 +65,8 @@ function encodeField(value) {
   if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
     return value;
   }
-  if (typeof value === "bigint" || value instanceof Date) {
-    return value instanceof Date ? value.toISOString() : value.toString();
+  if (value instanceof Date) {
+    return value.toISOString();
   }
   if (isRecord(value)) {
     return JSON.parse(JSON.stringify({ ...value, type: value.constructor.name }));

package/dist/jev/classifier.js

@@ -5,7 +5,7 @@ import {
   admissionPolicy,
   createJob,
   jevClient
-} from "./chunk-2UXHML67.js";
+} from "./chunk-PISXBJOT.js";
 
 // src/classifier.ts
 import { chunkers } from "../corpus/index.js";
@@ -81,7 +81,7 @@ function validatePredicate(predicate, kb) {
 function assertSupportedType(predicate) {
   for (const name of predicate.paramNames) {
     const type = predicate.params[name];
-    if (type === String || type === Number || type === BigInt || type === Date || type === void 0) {
+    if (type === String || type === Number || type === Date || type === void 0) {
       throw new UnsupportedPredicateError(
         `Cannot classify predicate "${predicate.name}": field "${name}" has an unsupported open-ended domain. Use Boolean, enumeration(...), or registered entities.`,
         predicate,

package/dist/jev/resolve.js

@@ -1,7 +1,7 @@
 import {
   admissionPolicy,
   jevAdjudicator
-} from "./chunk-2UXHML67.js";
+} from "./chunk-PISXBJOT.js";
 
 // src/resolve.ts
 function resolver(corpus, kb, config = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "factbag",
-  "version": "0.0.0-alpha.0",
+  "version": "0.0.0-alpha.2",
   "keywords": [
     "logic",
     "rules-engine",
@@ -76,7 +76,7 @@
     "@factbag/corpus": "0.1.0-next.0",
     "@factbag/guards": "0.1.0-next.0",
     "@factbag/jev": "0.1.0-next.0",
-    "@typesafe-ai/sdk": "0.6.0"
+    "@typesafe-ai/sdk": "0.7.0"
   },
   "peerDependencies": {
     "@typesafe-ai/sdk": "^0.6.0"