factbag 0.0.0-alpha.1 → 0.0.0-alpha.3

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # factbag
 
+## 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

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://daniel.du-pless.is/introducing-factbag) for how and
-why to use it, or [Jev and the Art of Truth Maintenance](https://daniel.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-X3LSDJL4.js → chunk-QOMFY3XB.js}

@@ -13,7 +13,10 @@ var PrimitiveArithmeticProgrammerError = class extends ProgrammerError {
   /** The arithmetic goal being evaluated when the failure occurred. */
   goal;
   constructor(operation, operands, goal) {
-    super(`${operation} expected numeric operands`);
+    const rounding = operation === "roundTo" || operation === "floorTo" || operation === "ceilTo";
+    super(
+      `${operation} expected ${operation === "daysBetween" || operation === "yearsBetween" ? "date" : "numeric"} operands${rounding ? " and a whole number of decimal places" : ""}`
+    );
     this.name = "PrimitiveArithmeticProgrammerError";
     this.operation = operation;
     this.operands = operands;

package/dist/core/{chunk-4IP7CXNV.js → chunk-RMQ3YX7V.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;
 }
@@ -82,5 +82,6 @@ export {
   isAtomForPredicate,
   atomEquals,
   fieldEquals,
-  fieldIdentityToken
+  fieldIdentityToken,
+  isEntityValue
 };

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.d.ts

@@ -6,9 +6,9 @@
  */
 export { and, exists, letIn, not, or } from "./formula.js";
 export { count, sum } from "./operators/aggregate.js";
-export type { AggregateBuilder, ComparableTerm, DateTerm, NumericTerm } from "./types.js";
-export { add, div, mul, sub } from "./operators/arithmetic.js";
-export { gt, gte, lte } from "./operators/comparison.js";
+export type { AggregateBuilder, ComparableTerm, DateTerm, EqualityTerm, NumericTerm, } from "./types.js";
+export { add, ceilTo, daysBetween, div, floorTo, max, min, mul, roundTo, sub, yearsBetween, } from "./operators/arithmetic.js";
+export { eq, gt, gte, lte, neq } from "./operators/comparison.js";
 export { closedPredicate, predicate } from "./predicate.js";
 export { enumeration } from "./enumeration.js";
 export type { ClosedWorldPredicate, OpenWorldPredicate, Predicate, PredicateBase, PredicateDeclaration, PredicateMetadata, PredicateWorld, } from "../types/predicate.js";

package/dist/core/dsl/index.js

@@ -1,11 +1,18 @@
 import {
   assertAtomLike,
   assertGroundAtom
-} from "../chunk-4IP7CXNV.js";
+} from "../chunk-RMQ3YX7V.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,98 @@ 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] };
 }
+function daysBetween(later, earlier) {
+  assertSupportedValue(later);
+  assertSupportedValue(earlier);
+  return { kind: "daysBetween", args: [later, earlier] };
+}
+function yearsBetween(later, earlier) {
+  assertSupportedValue(later);
+  assertSupportedValue(earlier);
+  return { kind: "yearsBetween", args: [later, earlier] };
+}
+function min(left, right) {
+  assertSupportedValue(left);
+  assertSupportedValue(right);
+  return { kind: "min", args: [left, right] };
+}
+function max(left, right) {
+  assertSupportedValue(left);
+  assertSupportedValue(right);
+  return { kind: "max", args: [left, right] };
+}
+function roundTo(value, places) {
+  assertSupportedValue(value);
+  assertSupportedValue(places);
+  return { kind: "roundTo", args: [value, places] };
+}
+function floorTo(value, places) {
+  assertSupportedValue(value);
+  assertSupportedValue(places);
+  return { kind: "floorTo", args: [value, places] };
+}
+function ceilTo(value, places) {
+  assertSupportedValue(value);
+  assertSupportedValue(places);
+  return { kind: "ceilTo", args: [value, places] };
+}
 
 // src/dsl/operators/comparison.ts
+function eq(left, right) {
+  assertSupportedValue(left);
+  assertSupportedValue(right);
+  return { kind: "eq", args: [left, right] };
+}
+function neq(left, right) {
+  assertSupportedValue(left);
+  assertSupportedValue(right);
+  return { kind: "neq", args: [left, right] };
+}
 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;
@@ -113,20 +183,29 @@ export {
   and,
   assertAtomLike,
   assertGroundAtom,
+  ceilTo,
   closedPredicate,
   count,
+  daysBetween,
   div,
   enumeration,
+  eq,
   exists,
+  floorTo,
   gt,
   gte,
   letIn,
   lte,
+  max,
+  min,
   mul,
+  neq,
   not,
   or,
   predicate,
+  roundTo,
   sub,
   sum,
-  variable
+  variable,
+  yearsBetween
 };

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,8 @@
 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 one numeric term from another. */
+export declare function sub(left: NumericTerm, right: NumericTerm): Formula<number, readonly [NumericTerm, NumericTerm]>;
 /**
  * Subtract a numeric duration in milliseconds from a date term, producing a
  * date expression.
@@ -19,9 +21,74 @@ 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]>;
 /** 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]>;
+/**
+ * Count signed UTC calendar days from `earlier` to `later`, ignoring time of day.
+ * Add one to count both the first and last day of a stay.
+ */
+export declare function daysBetween(later: DateTerm, earlier: DateTerm): Formula<number, readonly [DateTerm, DateTerm]>;
+/**
+ * Count signed whole years from `earlier` to `later` by UTC calendar anniversaries,
+ * ignoring time of day. February 29 anniversaries fall on March 1 in common years.
+ * A person's age on a day is `yearsBetween(day, birthday)`.
+ */
+export declare function yearsBetween(later: DateTerm, earlier: DateTerm): Formula<number, readonly [DateTerm, DateTerm]>;
+/**
+ * The lesser of two numeric terms.
+ *
+ * @example
+ * ```ts
+ * // Deduction reduction cannot exceed 80% of the deductions.
+ * letIn(R, min(mul(0.03, Excess), mul(0.8, Deductions)), gte(R, 0))
+ * ```
+ */
+export declare function min(left: NumericTerm, right: NumericTerm): Formula<number, readonly [NumericTerm, NumericTerm]>;
+/**
+ * The greater of two numeric terms.
+ *
+ * @example
+ * ```ts
+ * // The remaining allowance cannot be negative.
+ * letIn(A, max(sub(2000, Reduction), 0), gte(A, 0))
+ * ```
+ */
+export declare function max(left: NumericTerm, right: NumericTerm): Formula<number, readonly [NumericTerm, NumericTerm]>;
+/**
+ * Round to a whole number of decimal places, with halves away from zero.
+ * Negative places round to tens, hundreds, and so on. Decimal exponent shifting
+ * avoids multiplication artifacts such as `1.005 * 100`, so `roundTo(1.005, 2)`
+ * yields `1.01`. Inputs and results still have JavaScript number precision;
+ * this does not recover precision already lost in an earlier expression.
+ *
+ * @example
+ * ```ts
+ * // Tax is 15% of taxable income, in whole dollars.
+ * letIn(Tax, roundTo(mul(Income, 0.15), 0), gte(Tax, 0))
+ * ```
+ */
+export declare function roundTo(value: NumericTerm, places: NumericTerm): Formula<number, readonly [NumericTerm, NumericTerm]>;
+/**
+ * Round toward negative infinity at a whole number of decimal places.
+ * Negative places and decimal exponent shifting work as in {@link roundTo}.
+ *
+ * @example
+ * ```ts
+ * // Only complete thousands of eligible expenses count.
+ * letIn(Eligible, floorTo(Expenses, -3), gte(Eligible, 0))
+ * ```
+ */
+export declare function floorTo(value: NumericTerm, places: NumericTerm): Formula<number, readonly [NumericTerm, NumericTerm]>;
+/**
+ * Round toward positive infinity at a whole number of decimal places.
+ * Negative places and decimal exponent shifting work as in {@link roundTo}.
+ *
+ * @example
+ * ```ts
+ * // Two percentage points for each $2,500, or fraction thereof, of the excess.
+ * letIn(Points, mul(2, ceilTo(div(Excess, 2500), 0)), lte(Points, 100))
+ * ```
+ */
+export declare function ceilTo(value: NumericTerm, places: NumericTerm): Formula<number, readonly [NumericTerm, NumericTerm]>;