factbag 0.0.0-alpha.5 → 0.0.0-alpha.6

package/CHANGELOG.md

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

package/README.md

@@ -221,33 +221,25 @@ 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",
+  "because": "is_qualified_investor(person) if and(...)",
   "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"
-          }
-        }
-      ]
+      "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"
+      }
     }
   ]
 }

package/dist/dsl.d.ts

@@ -1,6 +1,6 @@
-import { A as PrimitiveGoal, B as Formula, C as LteGoal, Ct as Var, D as NeqGoal, Dt as PredicateSchema, E as MulGoal, Et as InferRuntime, F as AggregateBuilder, G as RuleBodyArgs, I as ComparableTerm, J as Scalar, K as RuleBodyInput, L as DateTerm, M as SubGoal, N as SumGoal, O as NotGoal, Ot as RuntimeConstructor, P as YearsBetweenGoal, R as EqualityTerm, S as LtGoal, St as Annotations, T as MinGoal, Tt as EnumType, V as FormulaArgumentInput, W as NumericTerm, Y as Term, _ as GoalExpression, _t as PredicateBase, a as ArithmeticKind, at as AnyAtom, b as GteGoal, bt as PredicateWorld, c as ComparisonGoal, ct as GroundFields, d as DaysBetweenGoal, dt as assertAtomLike, f as DivGoal, ft as assertGroundAtom, g as Goal, gt as Predicate, h as FloorToGoal, ht as OpenWorldPredicate, i as ArithmeticGoal, j as RoundToGoal, k as OrGoal, kt as RuntimeType, l as CompoundGoal, lt as NonGroundAtom, m as ExistsGoal, mt as ClosedWorldPredicate, n as AndGoal, nt as NegativeLiteral, o as AtomGoal, ot as Atom, p as EqGoal, pt as fieldEquals, r as AnyAtomGoal, s as CeilToGoal, st as GroundAtom, t as AddGoal, u as CountGoal, ut as PatternFields, v as GroundAtomGoal, vt as PredicateDeclaration, w as MaxGoal, wt as Entity, x as LetGoal, xt as AnnotationValue, y as GtGoal, yt as PredicateMetadata, z as ExistsArgs } from "./goal-BP745uKh.js";
-import { n as KnowledgeBase } from "./knowledge-base-Da5HLCsY.js";
-import { C as Bindings, S as Binding, _ as QueryAllJudgment, a as ErasedEvidenceSupport, b as SubgoalsSupport, c as Judgment, d as MissingBinding, f as NumericRange, g as PrimitiveUncertainty, h as PrimitiveSupportFor, i as CountPrimitiveSupport, l as JudgmentBase, m as PrimitiveSupport, n as ClosedWorldAbsenceSupport, o as ErasedRuleSupport, p as PrimitiveEvaluation, r as ComparisonPrimitiveSupport, s as EvidenceSupport, t as ArithmeticPrimitiveSupport, u as JudgmentSupportFor, v as QueryJudgment, w as GoalValue, x as SumPrimitiveSupport, y as RuleSupport } from "./judgment-Cr0JcUt5.js";
+import { A as OrGoal, At as RuntimeType, B as ExistsArgs, C as LtGoal, Ct as Annotations, D as MulGoal, Dt as InferRuntime, E as MinGoal, Et as EnumType, F as YearsBetweenGoal, G as NumericTerm, H as FormulaArgumentInput, I as AggregateBuilder, K as RuleBodyArgs, L as ComparableTerm, M as RoundToGoal, N as SubGoal, O as NeqGoal, Ot as PredicateSchema, P as SumGoal, R as DateTerm, S as LetGoal, St as AnnotationValue, T as MaxGoal, Tt as Entity, V as Formula, X as Term, Y as Scalar, _ as Goal, _t as Predicate, a as ArithmeticKind, b as GtGoal, bt as PredicateMetadata, c as ComparisonGoal, ct as GroundAtom, d as DaysBetweenGoal, dt as PatternFields, f as DivGoal, ft as assertAtomLike, g as FloorToGoal, gt as OpenWorldPredicate, h as FirstOfMonthGoal, ht as ClosedWorldPredicate, i as ArithmeticGoal, j as PrimitiveGoal, k as NotGoal, kt as RuntimeConstructor, l as CompoundGoal, lt as GroundFields, m as ExistsGoal, mt as fieldEquals, n as AndGoal, o as AtomGoal, ot as AnyAtom, p as EqGoal, pt as assertGroundAtom, q as RuleBodyInput, r as AnyAtomGoal, rt as NegativeLiteral, s as CeilToGoal, st as Atom, t as AddGoal, u as CountGoal, ut as NonGroundAtom, v as GoalExpression, vt as PredicateBase, w as LteGoal, wt as Var, x as GteGoal, xt as PredicateWorld, y as GroundAtomGoal, yt as PredicateDeclaration, z as EqualityTerm } from "./goal-BBoSfPUN.js";
+import { n as KnowledgeBase } from "./knowledge-base-CkU_xzmB.js";
+import { C as Bindings, S as Binding, _ as QueryAllJudgment, a as ErasedEvidenceSupport, b as SubgoalsSupport, c as Judgment, d as MissingBinding, f as NumericRange, g as PrimitiveUncertainty, h as PrimitiveSupportFor, i as CountPrimitiveSupport, l as JudgmentBase, m as PrimitiveSupport, n as ClosedWorldAbsenceSupport, o as ErasedRuleSupport, p as PrimitiveEvaluation, r as ComparisonPrimitiveSupport, s as EvidenceSupport, t as ArithmeticPrimitiveSupport, u as JudgmentSupportFor, v as QueryJudgment, w as GoalValue, x as SumPrimitiveSupport, y as RuleSupport } from "./judgment-v8i3ks5N.js";
 /**
  * Negate an atom in a rule body. Open-world predicates require explicit
  * negative support; closed-world predicates use negation-as-failure.
@@ -124,6 +124,28 @@ export declare function daysBetween(later: DateTerm, earlier: DateTerm): Formula
  * 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 first day of a month at UTC midnight, from a whole year and a whole month from 1
+ * (January) to 12. Other days of the year follow by date arithmetic.
+ *
+ * @example
+ * ```ts
+ * // The tax year Y runs from its first day to the day before the next year's.
+ * letIn(First, firstOfMonth(Y, 1), letIn(Last, sub(firstOfMonth(add(Y, 1), 1), dayMs), ...))
+ * ```
+ */
+export declare function firstOfMonth(year: NumericTerm, month: NumericTerm): Formula<Date, readonly [NumericTerm, NumericTerm]>;
+/**
+ * The UTC calendar year of a date, for dates from the year 0 on: the whole years from
+ * January 1 of the year 0, so it explains as that `yearsBetween`.
+ *
+ * @example
+ * ```ts
+ * // A death in an earlier year than Y.
+ * and(died({ person: P, day: D }), gt(Y, yearOf(D)))
+ * ```
+ */
+export declare function yearOf(date: DateTerm): Formula<number, readonly [DateTerm, DateTerm]>;
 /**
  * The lesser of two numeric terms.
  *
@@ -284,4 +306,4 @@ export declare function query<Schema extends PredicateSchema>(kb: KnowledgeBase,
  * ```
  */
 export declare function queryAll<Schema extends PredicateSchema>(kb: KnowledgeBase, pattern: Atom<Schema>): QueryAllJudgment<Schema>;
-export { type AddGoal, type AggregateBuilder, type AndGoal, type AnnotationValue, type Annotations, type AnyAtom, type AnyAtomGoal, type ArithmeticGoal, type ArithmeticKind, type ArithmeticPrimitiveSupport, type Atom, type AtomGoal, type Binding, type Bindings, type CeilToGoal, type ClosedWorldAbsenceSupport, type ClosedWorldPredicate, type ComparableTerm, type ComparisonGoal, type ComparisonPrimitiveSupport, type CompoundGoal, type CountGoal, type CountPrimitiveSupport, type DateTerm, type DaysBetweenGoal, type DivGoal, type Entity, type EnumType, type EqGoal, type EqualityTerm, type ErasedEvidenceSupport, type ErasedRuleSupport, type EvidenceSupport, type ExistsGoal, type FloorToGoal, type Formula, type Goal, type GoalExpression, type GoalValue, type GroundAtom, type GroundAtomGoal, type GroundFields, type GtGoal, type GteGoal, type InferRuntime, type Judgment, type JudgmentBase, type JudgmentSupportFor, type LetGoal, type LtGoal, type LteGoal, type MaxGoal, type MinGoal, type MissingBinding, type MulGoal, type NeqGoal, type NonGroundAtom, type NotGoal, type NumericRange, type NumericTerm, type OpenWorldPredicate, type OrGoal, type PatternFields, type Predicate, type PredicateBase, type PredicateDeclaration, type PredicateMetadata, type PredicateSchema, type PredicateWorld, type PrimitiveEvaluation, type PrimitiveGoal, type PrimitiveSupport, type PrimitiveSupportFor, type PrimitiveUncertainty, type QueryAllJudgment, type QueryJudgment, type RoundToGoal, type RuleSupport, type RuntimeConstructor, type RuntimeType, type Scalar, type SubGoal, type SubgoalsSupport, type SumGoal, type SumPrimitiveSupport, type Term, Var, type YearsBetweenGoal, assertAtomLike, assertGroundAtom, fieldEquals };
+export { type AddGoal, type AggregateBuilder, type AndGoal, type AnnotationValue, type Annotations, type AnyAtom, type AnyAtomGoal, type ArithmeticGoal, type ArithmeticKind, type ArithmeticPrimitiveSupport, type Atom, type AtomGoal, type Binding, type Bindings, type CeilToGoal, type ClosedWorldAbsenceSupport, type ClosedWorldPredicate, type ComparableTerm, type ComparisonGoal, type ComparisonPrimitiveSupport, type CompoundGoal, type CountGoal, type CountPrimitiveSupport, type DateTerm, type DaysBetweenGoal, type DivGoal, type Entity, type EnumType, type EqGoal, type EqualityTerm, type ErasedEvidenceSupport, type ErasedRuleSupport, type EvidenceSupport, type ExistsGoal, type FirstOfMonthGoal, type FloorToGoal, type Formula, type Goal, type GoalExpression, type GoalValue, type GroundAtom, type GroundAtomGoal, type GroundFields, type GtGoal, type GteGoal, type InferRuntime, type Judgment, type JudgmentBase, type JudgmentSupportFor, type LetGoal, type LtGoal, type LteGoal, type MaxGoal, type MinGoal, type MissingBinding, type MulGoal, type NeqGoal, type NonGroundAtom, type NotGoal, type NumericRange, type NumericTerm, type OpenWorldPredicate, type OrGoal, type PatternFields, type Predicate, type PredicateBase, type PredicateDeclaration, type PredicateMetadata, type PredicateSchema, type PredicateWorld, type PrimitiveEvaluation, type PrimitiveGoal, type PrimitiveSupport, type PrimitiveSupportFor, type PrimitiveUncertainty, type QueryAllJudgment, type QueryJudgment, type RoundToGoal, type RuleSupport, type RuntimeConstructor, type RuntimeType, type Scalar, type SubGoal, type SubgoalsSupport, type SumGoal, type SumPrimitiveSupport, type Term, Var, type YearsBetweenGoal, assertAtomLike, assertGroundAtom, fieldEquals };

package/dist/dsl.js

@@ -1,5 +1,5 @@
-import { i as Var } from "./types-0ZvnLf2N.js";
-import { a as fieldEquals, i as assertGroundAtom, n as queryAll, r as assertAtomLike, t as query } from "./query-Dxm7EpxZ.js";
+import { a as Var } from "./types-DeYyybXd.js";
+import { a as fieldEquals, i as assertGroundAtom, n as queryAll, r as assertAtomLike, t as query } from "./query-CN6EOPwp.js";
 // ../core/src/dsl/assert-supported-value.ts
 /** Reject removed scalar types before building rules or atoms. */
 function assertSupportedValue(value) {
@@ -206,6 +206,37 @@ function yearsBetween(later, earlier) {
 	};
 }
 /**
+* The first day of a month at UTC midnight, from a whole year and a whole month from 1
+* (January) to 12. Other days of the year follow by date arithmetic.
+*
+* @example
+* ```ts
+* // The tax year Y runs from its first day to the day before the next year's.
+* letIn(First, firstOfMonth(Y, 1), letIn(Last, sub(firstOfMonth(add(Y, 1), 1), dayMs), ...))
+* ```
+*/
+function firstOfMonth(year, month) {
+	assertSupportedValue(year);
+	assertSupportedValue(month);
+	return {
+		kind: "firstOfMonth",
+		args: [year, month]
+	};
+}
+/**
+* The UTC calendar year of a date, for dates from the year 0 on: the whole years from
+* January 1 of the year 0, so it explains as that `yearsBetween`.
+*
+* @example
+* ```ts
+* // A death in an earlier year than Y.
+* and(died({ person: P, day: D }), gt(Y, yearOf(D)))
+* ```
+*/
+function yearOf(date) {
+	return yearsBetween(date, firstOfMonth(0, 1));
+}
+/**
 * The lesser of two numeric terms.
 *
 * @example
@@ -442,4 +473,4 @@ function enumeration(first, ...rest) {
 function variable(name) {
 	return new Var(name);
 }
-export { Var, add, and, assertAtomLike, assertGroundAtom, ceilTo, closedPredicate, count, daysBetween, div, enumeration, eq, exists, fieldEquals, floorTo, gt, gte, letIn, lte, max, min, mul, neq, not, or, predicate, query, queryAll, roundTo, sub, sum, variable, yearsBetween };
+export { Var, add, and, assertAtomLike, assertGroundAtom, ceilTo, closedPredicate, count, daysBetween, div, enumeration, eq, exists, fieldEquals, firstOfMonth, floorTo, gt, gte, letIn, lte, max, min, mul, neq, not, or, predicate, query, queryAll, roundTo, sub, sum, variable, yearOf, yearsBetween };

package/dist/exceptions.d.ts

@@ -1,4 +1,4 @@
-import { Ct as Var, X as AnyRule, a as ArithmeticKind, i as ArithmeticGoal, vt as PredicateDeclaration } from "./goal-BP745uKh.js";
+import { Z as AnyRule, a as ArithmeticKind, i as ArithmeticGoal, wt as Var, yt as PredicateDeclaration } from "./goal-BBoSfPUN.js";
 /** Base class for errors that mean the caller supplied invalid program logic. */
 export declare class ProgrammerError extends Error {
   constructor(message: string);

package/dist/exceptions.js

@@ -1 +1 @@
-export { t as ExclusiveDefinitionProgrammerError, n as PrimitiveArithmeticProgrammerError, r as ProgrammerError, i as UnconstructiveRecursionProgrammerError, a as UnsafeUnboundVariableProgrammerError, o as UnsupportedPredicateError } from "./programmer-errors-DDfy03Y0.js";
+export { t as ExclusiveDefinitionProgrammerError, n as PrimitiveArithmeticProgrammerError, r as ProgrammerError, i as UnconstructiveRecursionProgrammerError, a as UnsafeUnboundVariableProgrammerError, o as UnsupportedPredicateError } from "./programmer-errors-DLE1xWJ_.js";

package/dist/explain.d.ts

@@ -1,8 +1,14 @@
-import { c as Judgment } from "./judgment-Cr0JcUt5.js";
+import { c as Judgment } from "./judgment-v8i3ks5N.js";
 /** Shared shape for every compact, LLM-readable explanation node. */
 type ExplanationBase = Readonly<{
   /** The evaluated claim and its value, e.g. `eligible(alice) = true`. */
   claim: string;
+  /**
+   * Claims this one also rests on that a budget left unexplained, each with its value,
+   * e.g. `resident(alice) = true`. What decided a claim is explained before what did
+   * not, so these are most often claims that were evaluated and changed nothing.
+   */
+  notShown?: readonly string[];
 }>;
 /**
  * A compact, LLM-readable explanation node.
@@ -12,7 +18,7 @@ type ExplanationBase = Readonly<{
  * ```json
  * {
  *   "claim": "eligible(alice) = true",
- *   "because": "eligible(P) iff not(active_sanction(P)), with P = alice",
+ *   "because": "eligible(P) iff not(active_sanction(P))",
  *   "given": [
  *     {
  *       "claim": "not(active_sanction(alice)) = true",
@@ -33,7 +39,7 @@ type Explanation = EvidenceExplanation | DerivedExplanation | CompoundExplanatio
  *   "claim": "active_sanction(bob) = true",
  *   "because": {
  *     "source": "sanctions_registry",
- *     "quote": "Bob appears on the active sanctions list."
+ *     "citation": "Bob appears on the active sanctions list."
  *   }
  * }
  * ```
@@ -47,12 +53,12 @@ type Explanation = EvidenceExplanation | DerivedExplanation | CompoundExplanatio
  *     {
  *       "claim": "active_sanction(drew) = true",
  *       "source": "sanctions_registry",
- *       "quote": "Drew appears on the active sanctions list."
+ *       "citation": "Drew appears on the active sanctions list."
  *     },
  *     {
  *       "claim": "active_sanction(drew) = false",
  *       "source": "appeals_board",
- *       "quote": "Drew's sanction was overturned on appeal."
+ *       "citation": "Drew's sanction was overturned on appeal."
  *     }
  *   ]
  * }
@@ -69,7 +75,7 @@ type EvidenceExplanation = ExplanationBase & Readonly<{
  * ```json
  * {
  *   "claim": "eligible(bob) = false",
- *   "because": "eligible(P) iff not(active_sanction(P)), with P = bob",
+ *   "because": "eligible(P) iff not(active_sanction(P))",
  *   "given": [
  *     {
  *       "claim": "not(active_sanction(bob)) = false",
@@ -78,7 +84,7 @@ type EvidenceExplanation = ExplanationBase & Readonly<{
  *           "claim": "active_sanction(bob) = true",
  *           "because": {
  *             "source": "sanctions_registry",
- *             "quote": "Bob appears on the active sanctions list."
+ *             "citation": "Bob appears on the active sanctions list."
  *           }
  *         }
  *       ]
@@ -106,12 +112,12 @@ type DerivedExplanation = ExplanationBase & Readonly<{
  *         {
  *           "claim": "active_sanction(drew) = true",
  *           "source": "sanctions_registry",
- *           "quote": "Drew appears on the active sanctions list."
+ *           "citation": "Drew appears on the active sanctions list."
  *         },
  *         {
  *           "claim": "active_sanction(drew) = false",
  *           "source": "appeals_board",
- *           "quote": "Drew's sanction was overturned on appeal."
+ *           "citation": "Drew's sanction was overturned on appeal."
  *         }
  *       ]
  *     }
@@ -146,7 +152,7 @@ type TerminalExplanation = ExplanationBase & Readonly<{
  * ```json
  * {
  *   "source": "sanctions_registry",
- *   "quote": "Bob appears on the active sanctions list."
+ *   "citation": "Bob appears on the active sanctions list."
  * }
  * ```
  *
@@ -156,28 +162,48 @@ type TerminalExplanation = ExplanationBase & Readonly<{
  * {
  *   "claim": "active_sanction(drew) = false",
  *   "source": "appeals_board",
- *   "quote": "Drew's sanction was overturned on appeal.",
+ *   "citation": "Drew's sanction was overturned on appeal.",
  *   "metadata": { "reviewed_by": "appeals_panel" }
  * }
  * ```
  */
 type EvidenceReason = Readonly<{
-  /** Optional when the surrounding `claim` already names what the evidence proves. */
+  /**
+   * What this evidence says, e.g. `active_sanction(drew) = false`. Left out when it only
+   * repeats the claim of the explanation it sits under and the evidence has provenance.
+   */
   claim?: string;
   /** Where the evidence came from, e.g. `sanctions_registry`. */
   source?: string;
-  /** The quoted text or excerpt that supports the evidence claim. */
-  quote?: string;
+  /** The words of the source that support the claim, as recorded with the evidence. */
+  citation?: string;
+  /** Why the citation supports the claim, as stated by whoever recorded the evidence. */
+  justification?: string;
   /** Raw source-specific details that should not be flattened into prose. */
   metadata?: Readonly<Record<string, unknown>>;
 }>;
+/**
+ * How much of a judgment's proof to explain.
+ */
+type ExplanationOptions = Readonly<{
+  /**
+   * The most claims to explain. Without it, every claim of the proof is explained.
+   *
+   * Most of a proof is conditions that held and changed nothing, and a deep rule set has
+   * hundreds of them. Within a budget, the conclusion is always explained, then what
+   * decided it before what did not, and what is near it before what is far. A claim that
+   * rests on claims left out names them, with their values, in `notShown`.
+   */
+  budget?: number;
+}>;
 /**
  * Convert a judgment's proof-support graph into a compact, LLM-readable
  * {@link Explanation} of what was concluded and why.
  *
- * The result is a directed acyclic graph (DAG): reused judgment objects share
- * explanation nodes within this call. Serializing the result as JSON still
- * expands shared nodes at every path to them.
+ * Without a budget, the result is a directed acyclic graph (DAG): reused judgment
+ * objects share explanation nodes within this call. Serializing it as JSON expands a
+ * shared node at every path to it, so the text of a deep proof grows with its paths, to
+ * megabytes. Give a `budget` to explain a judgment in text.
  *
  * @example
  * ```ts
@@ -187,10 +213,13 @@ type EvidenceReason = Readonly<{
  * ```json
  * {
  *   "claim": "doctor(alice) = true",
- *   "because": "doctor(P) iff and(passed_medical_school(P), has_active_license(P)), with P = alice",
- *   "given": [{ "claim": "and(...) = true" }]
+ *   "because": "doctor(P) iff and(passed_medical_school(P), has_active_license(P))",
+ *   "given": [
+ *     { "claim": "passed_medical_school(alice) = true" },
+ *     { "claim": "has_active_license(alice) = true" }
+ *   ]
  * }
  * ```
  */
-export declare function explainJudgment(judgment: Judgment): Explanation;
-export type { CompoundExplanation, DerivedExplanation, EvidenceExplanation, EvidenceReason, Explanation, ExplanationBase, TerminalExplanation };
+export declare function explainJudgment(judgment: Judgment, options?: ExplanationOptions): Explanation;
+export type { CompoundExplanation, DerivedExplanation, EvidenceExplanation, EvidenceReason, Explanation, ExplanationBase, ExplanationOptions, TerminalExplanation };

package/dist/explain.js

@@ -1,12 +1,96 @@
-import { a as isVar, n as AssertionError, t as isFormula } from "./types-0ZvnLf2N.js";
+import { n as AssertionError, o as isTemporary, s as isVar, t as isFormula } from "./types-DeYyybXd.js";
+// ../core/src/explanation/relevance.ts
+/**
+* Which of the claims an explanation rests on did not decide its value.
+*
+* A false conjunction is false because of its false conditions; the true ones were
+* evaluated and changed nothing. That is not part of what an explanation says, so it is
+* kept beside the explanation rather than in it, for writing an explanation out within a
+* budget: what decided a claim is worth a reader's attention before what did not.
+*/
+const undecisive = /* @__PURE__ */ new WeakMap();
+/** Record the claims under `explanation` that did not decide its value. */
+function noteUndecisive(explanation, claims) {
+	const noted = new Set(claims);
+	if (noted.size > 0) undecisive.set(explanation, noted);
+}
+/** The claims under `explanation` that did not decide its value. None, if none were recorded. */
+function undecisiveIn(explanation) {
+	return undecisive.get(explanation) ?? NONE;
+}
+const NONE = /* @__PURE__ */ new Set();
+// ../core/src/explanation/budget.ts
+/**
+* The explanation cut down to its `budget` claims most worth a reader's attention, the
+* conclusion first. A claim that rests on claims left out names them in `notShown`.
+*
+* A claim is as far from the conclusion as the fewest undecisive claims on the way to
+* it, then as the number of claims on the way. So what decided the conclusion is kept
+* before anything that did not, the conditions of the conclusion's own rule before those
+* of a rule three levels down, and no claim is kept without the claim that rests on it.
+*
+* The budget counts claims as they are written out, so a claim that two others rest on
+* counts under each: the result written as JSON has at most `budget` nodes.
+*/
+function withinBudget(explanation, budget) {
+	const root = {
+		source: explanation,
+		children: /* @__PURE__ */ new Map()
+	};
+	const frontier = candidates(root, [0, 0]);
+	for (let kept = 1; kept < budget; kept++) {
+		const nearest = frontier.reduce((best, candidate) => best === void 0 || nearer(candidate.distance, best.distance) ? candidate : best, void 0);
+		if (nearest === void 0) break;
+		frontier.splice(frontier.indexOf(nearest), 1);
+		const child = {
+			source: nearest.source,
+			children: /* @__PURE__ */ new Map()
+		};
+		nearest.under.children.set(nearest.source, child);
+		frontier.push(...candidates(child, nearest.distance));
+	}
+	return write(root);
+}
+function nearer(a, b) {
+	return a[0] < b[0] || a[0] === b[0] && a[1] < b[1];
+}
+function candidates(kept, distance) {
+	const { source } = kept;
+	const undecisive = undecisiveIn(source);
+	return ("given" in source ? source.given : []).map((child) => ({
+		source: child,
+		under: kept,
+		distance: [distance[0] + (undecisive.has(child) ? 1 : 0), distance[1] + 1]
+	}));
+}
+function write(kept) {
+	const { source } = kept;
+	if (!("given" in source)) return source;
+	const given = [];
+	const notShown = [];
+	for (const child of source.given) {
+		const keptChild = kept.children.get(child);
+		if (keptChild === void 0) notShown.push(child.claim);
+		else given.push(write(keptChild));
+	}
+	return notShown.length === 0 ? {
+		...source,
+		given
+	} : {
+		...source,
+		given,
+		notShown: [...new Set(notShown)]
+	};
+}
 // ../core/src/explanation/explain.ts
 /**
 * Convert a judgment's proof-support graph into a compact, LLM-readable
 * {@link Explanation} of what was concluded and why.
 *
-* The result is a directed acyclic graph (DAG): reused judgment objects share
-* explanation nodes within this call. Serializing the result as JSON still
-* expands shared nodes at every path to them.
+* Without a budget, the result is a directed acyclic graph (DAG): reused judgment
+* objects share explanation nodes within this call. Serializing it as JSON expands a
+* shared node at every path to it, so the text of a deep proof grows with its paths, to
+* megabytes. Give a `budget` to explain a judgment in text.
 *
 * @example
 * ```ts
@@ -16,17 +100,22 @@ import { a as isVar, n as AssertionError, t as isFormula } from "./types-0ZvnLf2
 * ```json
 * {
 *   "claim": "doctor(alice) = true",
-*   "because": "doctor(P) iff and(passed_medical_school(P), has_active_license(P)), with P = alice",
-*   "given": [{ "claim": "and(...) = true" }]
+*   "because": "doctor(P) iff and(passed_medical_school(P), has_active_license(P))",
+*   "given": [
+*     { "claim": "passed_medical_school(alice) = true" },
+*     { "claim": "has_active_license(alice) = true" }
+*   ]
 * }
 * ```
 */
-function explainJudgment(judgment) {
-	return explainWithContext(judgment, {
+function explainJudgment(judgment, options = {}) {
+	const explanation = explainWithContext(judgment, {
+		definitions: /* @__PURE__ */ new Map(),
 		explanations: /* @__PURE__ */ new WeakMap(),
 		contentKeys: /* @__PURE__ */ new WeakMap(),
 		keyIds: /* @__PURE__ */ new Map()
 	});
+	return options.budget === void 0 ? explanation : withinBudget(explanation, options.budget);
 }
 function explainWithContext(judgment, context) {
 	let explanation = context.explanations.get(judgment);
@@ -40,40 +129,94 @@ function explainOnce(judgment, context) {
 	if (isClosedWorldAbsence(judgment)) {
 		const atom = judgment.goal.goal.atom;
 		return {
-			claim: claimForJudgment(judgment),
-			because: `${formatAtom(atom)} is closed-world, and no evidence is known`
+			claim: claimForJudgment(judgment, context),
+			because: `${formatAtom(atom, scopeOf(judgment, context))} is closed-world, and no evidence is known`
 		};
 	}
 	const supports = supportsForValue(judgment);
 	const ruleSupport = supports.find((support) => support.source === "rule");
-	if (ruleSupport !== void 0) return {
-		claim: claimForJudgment(judgment),
-		because: formatRuleApplication(ruleSupport.rule, ruleSupport.body.bindings),
-		given: [explainWithContext(ruleSupport.body, context)]
-	};
+	if (ruleSupport !== void 0) {
+		const body = explainWithContext(ruleSupport.body, context);
+		const explanation = {
+			claim: claimForJudgment(judgment, context),
+			because: formatRule(ruleSupport.rule),
+			given: ruleBodyExplanations(ruleSupport.body, body)
+		};
+		noteUndecisive(explanation, undecisiveIn(body));
+		return explanation;
+	}
 	const evidence = supports.flatMap((support) => support.source === "evidence" ? support.literals : []);
 	if (evidence.length > 0) {
-		const reasons = evidence.map(evidenceReason);
+		const claim = claimForJudgment(judgment, context);
+		const reasons = evidence.map((literal) => evidenceReason(literal, claim));
 		const firstReason = reasons[0];
 		return {
-			claim: claimForJudgment(judgment),
+			claim,
 			because: reasons.length === 1 && firstReason !== void 0 ? firstReason : reasons
 		};
 	}
 	const subgoals = supports.flatMap((support) => support.source === "subgoals" ? support.judgments : []);
-	if (subgoals.length > 0) return {
-		claim: claimForJudgment(judgment),
-		given: uniqueExplanations(subgoals.map((subgoal) => explainWithContext(subgoal, context)), context)
-	};
+	if (subgoals.length > 0) {
+		const explanation = {
+			claim: claimForJudgment(judgment, context),
+			given: uniqueExplanations(subgoals.map((subgoal) => explainWithContext(subgoal, context)), context)
+		};
+		const deciding = new Set(decidingSubgoals(judgment, subgoals).map((subgoal) => explainWithContext(subgoal, context)));
+		noteUndecisive(explanation, explanation.given.filter((given) => !deciding.has(given)));
+		return explanation;
+	}
 	if (supports.find((support) => support.source === "closed-world-absence") !== void 0 && judgment.goal.kind === "atom") return {
-		claim: claimForJudgment(judgment),
-		because: `${formatAtom(judgment.goal.atom)} is closed-world, and no matching evidence is known`
+		claim: claimForJudgment(judgment, context),
+		because: `${formatAtom(judgment.goal.atom, scopeOf(judgment, context))} is closed-world, and no matching evidence is known`
+	};
+	const primitive = supports.find((support) => support.source === "primitive");
+	if (primitive !== void 0) return {
+		claim: claimForJudgment(judgment, context),
+		because: primitiveReason(primitive, scopeOf(judgment, context))
 	};
 	return {
-		claim: claimForJudgment(judgment),
+		claim: claimForJudgment(judgment, context),
 		because: "no supporting evidence or rule was found"
 	};
 }
+/**
+* Why a comparison, arithmetic term or aggregate has its value. It is computed rather than
+* supported by evidence or a rule, unless a variable it needs was never given a value.
+*/
+function primitiveReason(support, scope) {
+	const uncertainty = support.source === "primitive" && "evaluation" in support ? support.evaluation.uncertainty ?? [] : [];
+	const missing = uncertainty.flatMap((reason) => reason.kind === "missing-binding" ? [formatValue(reason.variable, scope)] : []);
+	if (missing.length > 0) return `${[...new Set(missing)].join(", ")} ${missing.length === 1 ? "has" : "have"} no value`;
+	return uncertainty.length > 0 ? "computed from values that are not settled" : "computed";
+}
+/**
+* What a rule application rests on. A body that is an `and` or an `or` is not a step of
+* its own: the rule already states it, so the application rests directly on the body's
+* subgoals. Any other body, such as a single atom or a negation, is the one thing it
+* rests on.
+*/
+function ruleBodyExplanations(body, explanation) {
+	return (body.goal.kind === "and" || body.goal.kind === "or") && "given" in explanation && !("because" in explanation) ? explanation.given : [explanation];
+}
+/**
+* The subgoals that give a conjunction or disjunction its value. The rest were evaluated
+* and changed nothing.
+*
+* A false `and` is decided by its false subgoals, all of them: each is something that
+* would have to change. A true `or` is decided by one true subgoal, and the first will
+* do. A true `and` and a false `or` need every subgoal. When the value is not settled,
+* the subgoals that are not settled either way are what it waits on.
+*/
+function decidingSubgoals(judgment, subgoals) {
+	const { kind } = judgment.goal;
+	if (kind !== "and" && kind !== "or") return subgoals;
+	const deciding = kind === "and" ? "false" : "true";
+	const neutral = kind === "and" ? "true" : "false";
+	if (judgment.value === neutral) return subgoals;
+	const decided = judgment.value === deciding ? subgoals.filter((subgoal) => subgoal.value === deciding) : subgoals.filter((subgoal) => subgoal.value !== neutral);
+	const chosen = kind === "or" && judgment.value === "true" ? decided.slice(0, 1) : decided;
+	return chosen.length > 0 ? chosen : subgoals;
+}
 function uniqueExplanations(explanations, context) {
 	const seen = /* @__PURE__ */ new Set();
 	const unique = [];
@@ -125,21 +268,86 @@ function isClosedWorldAbsence(judgment) {
 	if (child.value === "unknown") return true;
 	return child.value === "false" && child.negative.some((childSupport) => childSupport.source === "closed-world-absence");
 }
-function claimForJudgment(judgment) {
-	return `${formatGoal(judgment.goal)} = ${judgment.value}`;
+const NO_SCOPE = {
+	values: /* @__PURE__ */ new Map(),
+	definitions: /* @__PURE__ */ new Map()
+};
+function scopeOf(judgment, context) {
+	noteDefinitions(judgment.goal, context.definitions);
+	return {
+		values: new Map(judgment.bindings),
+		definitions: context.definitions
+	};
+}
+/** Record the term that computes each temporary in the goal. A parent is always noted before its subgoals are explained. */
+function noteDefinitions(goal, definitions) {
+	if ("bind" in goal && isTemporary(goal.bind)) definitions.set(goal.bind, goal);
+	if (goal.kind === "and" || goal.kind === "or") for (const subgoal of goal.goals) noteDefinitions(subgoal, definitions);
+}
+/**
+* The goal as it was evaluated, and what it came to. Variables are written as the values
+* they hold, and a variable without one keeps its name. A term that computes a value says
+* the value it computed, such as `A = mul(1000, 0.15) = 150`; every other claim ends in
+* its truth value. A temporary is never named: the term that computes it stands for it.
+*/
+function claimForJudgment(judgment, context) {
+	const scope = scopeOf(judgment, context);
+	const { goal } = judgment;
+	if ("bind" in goal) {
+		const result = scope.values.has(goal.bind) && judgment.value === "true" ? formatValue(scope.values.get(goal.bind)) : judgment.value;
+		return `${formatComputation(goal, scope)} = ${result}`;
+	}
+	return `${formatGoal(goal, scope)} = ${judgment.value}`;
 }
-function evidenceReason(literal) {
+/**
+* A computing goal with the variable it binds left as a name, `A = mul(1000, 0.15)`, or
+* with no name when it binds a temporary, `mul(1000, 0.15)`.
+*/
+function formatComputation(goal, scope) {
+	const values = new Map(scope.values);
+	values.delete(goal.bind);
+	const term = formatTerm(goal, {
+		...scope,
+		values
+	});
+	return isTemporary(goal.bind) ? term : `${goal.bind.name} = ${term}`;
+}
+/**
+* A computing goal inside a larger one: the term and its value, `mul(1000, 0.15) = 150`,
+* or with no value the variable it would bind, `A = mul(I, 0.15)`. A temporary with no
+* value is written as its term wherever it is used, so here it is the term alone.
+*/
+function formatComputing(goal, scope) {
+	const term = formatTerm(goal, scope);
+	if (scope.values.has(goal.bind)) return `${term} = ${formatValue(scope.values.get(goal.bind))}`;
+	return isTemporary(goal.bind) ? term : `${goal.bind.name} = ${term}`;
+}
+/** The computation itself, without the variable it binds: `mul(1000, 0.15)`. */
+function formatTerm(goal, scope) {
+	if (goal.kind === "sum") return `sum(${formatValue(goal.value, scope)})`;
+	if (goal.kind === "count") return `count(${formatGoal(goal.where, scope)})`;
+	return `${goal.kind}(${formatValue(goal.left, scope)}, ${formatValue(goal.right, scope)})`;
+}
+/**
+* What one piece of evidence says and where it comes from. Its claim is left out when it
+* only repeats `stepClaim` beside provenance, so a step states its claim once.
+*/
+function evidenceReason(literal, stepClaim) {
 	const claim = `${formatAtom(literal.atom)} = ${literal.sign === "+" ? "true" : "false"}`;
-	const source = literal.metadata?.source;
-	return source === void 0 ? { claim } : {
+	const { source, citation, justification } = literal.metadata ?? {};
+	const provenance = {
+		...source === void 0 ? {} : { source },
+		...citation === void 0 ? {} : { citation },
+		...justification === void 0 ? {} : { justification }
+	};
+	return claim === stepClaim && Object.keys(provenance).length > 0 ? provenance : {
 		claim,
-		source
+		...provenance
 	};
 }
-function formatRuleApplication(rule, bindings) {
-	const base = `${formatLiteral(rule.head)} ${rule.kind} ${formatRuleBody(rule.body)}`;
-	if (bindings.length === 0) return base;
-	return `${base}, with ${bindings.map(([variable, value]) => `${variable.name} = ${formatValue(value)}`).join(", ")}`;
+/** A rule as its author wrote it. The values it was applied to are in the claims it supports. */
+function formatRule(rule) {
+	return `${formatLiteral(rule.head)} ${rule.kind} ${formatRuleBody(rule.body)}`;
 }
 function formatRuleBody(body) {
 	if (isLiteral(body)) return formatLiteral(body);
@@ -150,44 +358,52 @@ function formatRuleBody(body) {
 function formatLiteral(literal) {
 	return literal.sign === "-" ? `not(${formatAtom(literal.atom)})` : formatAtom(literal.atom);
 }
-function formatGoal(goal) {
+function formatGoal(goal, scope = NO_SCOPE) {
 	switch (goal.kind) {
-		case "atom": return formatAtom(goal.atom);
-		case "not": return `not(${formatGoal(goal.goal)})`;
+		case "atom": return formatAtom(goal.atom, scope);
+		case "not": return `not(${formatGoal(goal.goal, scope)})`;
 		case "and":
-		case "or": return `${goal.kind}(${goal.goals.map(formatGoal).join(", ")})`;
-		case "exists": return `exists(${goal.variables.map((variable) => variable.name).join(", ")}: ${formatGoal(goal.goal)})`;
-		case "let": return `let(${goal.variable.name} = ${formatValue(goal.value)}: ${formatGoal(goal.goal)})`;
+		case "or": return `${goal.kind}(${goal.goals.map((subgoal) => formatGoal(subgoal, scope)).join(", ")})`;
+		case "exists": return `exists(${goal.variables.map((variable) => variable.name).join(", ")}: ${formatGoal(goal.goal, scope)})`;
+		case "let": return `let(${goal.variable.name} = ${formatValue(goal.value, scope)}: ${formatGoal(goal.goal, scope)})`;
 		case "add":
 		case "sub":
 		case "mul":
 		case "div":
 		case "daysBetween":
 		case "yearsBetween":
+		case "firstOfMonth":
 		case "min":
 		case "max":
 		case "roundTo":
 		case "floorTo":
-		case "ceilTo": return `${goal.bind.name} = ${goal.kind}(${formatValue(goal.left)}, ${formatValue(goal.right)})`;
+		case "ceilTo":
+		case "sum":
+		case "count": return formatComputing(goal, scope);
 		case "eq":
 		case "neq":
 		case "lt":
 		case "lte":
 		case "gt":
-		case "gte": return `${goal.kind}(${formatValue(goal.left)}, ${formatValue(goal.right)})`;
-		case "sum": return `${goal.bind.name} = sum(${formatValue(goal.value)})`;
-		case "count": return `${goal.bind.name} = count(${formatGoal(goal.where)})`;
+		case "gte": return `${goal.kind}(${formatValue(goal.left, scope)}, ${formatValue(goal.right, scope)})`;
 		default: throw new AssertionError("Unhandled goal kind");
 	}
 }
-function formatAtom(atom) {
-	const values = atom.predicate.paramNames.map((name) => formatValue(atom.fields[name]));
-	return `${atom.predicate.name}(${values.join(", ")})`;
+function formatAtom(atom, scope = NO_SCOPE) {
+	const fields = atom.predicate.paramNames.map((name) => formatValue(atom.fields[name], scope));
+	return `${atom.predicate.name}(${fields.join(", ")})`;
 }
-function formatValue(value) {
-	if (isVar(value)) return value.name;
+function formatValue(value, scope = NO_SCOPE) {
+	if (isVar(value)) {
+		if (scope.values.has(value)) return formatValue(scope.values.get(value));
+		const definition = scope.definitions.get(value);
+		return definition === void 0 ? value.name : formatTerm(definition, scope);
+	}
 	if (typeof value === "object" && value !== null && "id" in value && typeof value.id === "string") return value.id;
-	if (value instanceof Date) return value.toISOString();
+	if (value instanceof Date) {
+		const text = value.toISOString();
+		return text.endsWith("T00:00:00.000Z") ? text.slice(0, 10) : text;
+	}
 	return String(value);
 }
 function isLiteral(value) {

package/dist/{goal-BP745uKh.d.ts → goal-BBoSfPUN.d.ts}

@@ -270,6 +270,8 @@ type DivGoal = ArithmeticGoal<"div">;
 type DaysBetweenGoal = ArithmeticGoal<"daysBetween">;
 /** Arithmetic goal binding whole anniversary years from the right date to the left. */
 type YearsBetweenGoal = ArithmeticGoal<"yearsBetween">;
+/** Arithmetic goal binding the first day of the right month of the left year. */
+type FirstOfMonthGoal = ArithmeticGoal<"firstOfMonth">;
 /** Arithmetic goal binding the lesser of two numeric expressions. */
 type MinGoal = ArithmeticGoal<"min">;
 /** Arithmetic goal binding the greater of two numeric expressions. */
@@ -281,7 +283,7 @@ type FloorToGoal = ArithmeticGoal<"floorTo">;
 /** Arithmetic goal rounding toward positive infinity at the right operand's decimal places. */
 type CeilToGoal = ArithmeticGoal<"ceilTo">;
 /** The primitive arithmetic operations. */
-type ArithmeticKind = "add" | "sub" | "mul" | "div" | "daysBetween" | "yearsBetween" | "min" | "max" | "roundTo" | "floorTo" | "ceilTo";
+type ArithmeticKind = "add" | "sub" | "mul" | "div" | "daysBetween" | "yearsBetween" | "firstOfMonth" | "min" | "max" | "roundTo" | "floorTo" | "ceilTo";
 /** Bind the result of a primitive arithmetic operation. */
 type ArithmeticGoal<Kind extends ArithmeticKind> = Readonly<{
   readonly kind: Kind;
@@ -323,9 +325,9 @@ type CountGoal = Readonly<{
   readonly completeWhen?: Goal;
 }>;
 /** A normalized rule-body target that the solver/proof system can evaluate. */
-type Goal = AnyAtomGoal | NotGoal | AndGoal | OrGoal | ExistsGoal | LetGoal | AddGoal | SubGoal | MulGoal | DivGoal | DaysBetweenGoal | YearsBetweenGoal | MinGoal | MaxGoal | RoundToGoal | FloorToGoal | CeilToGoal | EqGoal | NeqGoal | LtGoal | LteGoal | GtGoal | GteGoal | SumGoal | CountGoal;
+type Goal = AnyAtomGoal | NotGoal | AndGoal | OrGoal | ExistsGoal | LetGoal | AddGoal | SubGoal | MulGoal | DivGoal | DaysBetweenGoal | YearsBetweenGoal | FirstOfMonthGoal | MinGoal | MaxGoal | RoundToGoal | FloorToGoal | CeilToGoal | EqGoal | NeqGoal | LtGoal | LteGoal | GtGoal | GteGoal | SumGoal | CountGoal;
 /** A goal evaluated by recursively evaluating one or more child goals. */
 type CompoundGoal = NotGoal | AndGoal | OrGoal | ExistsGoal | LetGoal;
 /** A goal evaluated directly by a primitive operator. */
-type PrimitiveGoal = AddGoal | SubGoal | MulGoal | DivGoal | DaysBetweenGoal | YearsBetweenGoal | MinGoal | MaxGoal | RoundToGoal | FloorToGoal | CeilToGoal | EqGoal | NeqGoal | LtGoal | LteGoal | GtGoal | GteGoal | SumGoal | CountGoal;
-export { AnyLiteral as $, PrimitiveGoal as A, Formula as B, LteGoal as C, Var as Ct, NeqGoal as D, PredicateSchema as Dt, MulGoal as E, InferRuntime as Et, AggregateBuilder as F, RuleBodyArgs as G, LiteralArgs as H, ComparableTerm as I, Scalar as J, RuleBodyInput as K, DateTerm as L, SubGoal as M, SumGoal as N, NotGoal as O, RuntimeConstructor as Ot, YearsBetweenGoal as P, RuleKind as Q, EqualityTerm as R, LtGoal as S, Annotations as St, MinGoal as T, EnumType as Tt, LiteralFilter as U, FormulaArgumentInput as V, NumericTerm as W, AnyRule as X, Term as Y, Rule as Z, GoalExpression as _, PredicateBase as _t, ArithmeticKind as a, AnyAtom as at, GteGoal as b, PredicateWorld as bt, ComparisonGoal as c, GroundFields as ct, DaysBetweenGoal as d, assertAtomLike as dt, Literal as et, DivGoal as f, assertGroundAtom as ft, Goal as g, Predicate as gt, FloorToGoal as h, OpenWorldPredicate as ht, ArithmeticGoal as i, EvidenceMetadata as it, RoundToGoal as j, OrGoal as k, RuntimeType as kt, CompoundGoal as l, NonGroundAtom as lt, ExistsGoal as m, ClosedWorldPredicate as mt, AndGoal as n, NegativeLiteral as nt, AtomGoal as o, Atom as ot, EqGoal as p, fieldEquals as pt, RuleBuilder as q, AnyAtomGoal as r, PositiveLiteral as rt, CeilToGoal as s, GroundAtom as st, AddGoal as t, LiteralSign as tt, CountGoal as u, PatternFields as ut, GroundAtomGoal as v, PredicateDeclaration as vt, MaxGoal as w, Entity as wt, LetGoal as x, AnnotationValue as xt, GtGoal as y, PredicateMetadata as yt, ExistsArgs as z };
+type PrimitiveGoal = AddGoal | SubGoal | MulGoal | DivGoal | DaysBetweenGoal | YearsBetweenGoal | FirstOfMonthGoal | MinGoal | MaxGoal | RoundToGoal | FloorToGoal | CeilToGoal | EqGoal | NeqGoal | LtGoal | LteGoal | GtGoal | GteGoal | SumGoal | CountGoal;
+export { RuleKind as $, OrGoal as A, RuntimeType as At, ExistsArgs as B, LtGoal as C, Annotations as Ct, MulGoal as D, InferRuntime as Dt, MinGoal as E, EnumType as Et, YearsBetweenGoal as F, NumericTerm as G, FormulaArgumentInput as H, AggregateBuilder as I, RuleBuilder as J, RuleBodyArgs as K, ComparableTerm as L, RoundToGoal as M, SubGoal as N, NeqGoal as O, PredicateSchema as Ot, SumGoal as P, Rule as Q, DateTerm as R, LetGoal as S, AnnotationValue as St, MaxGoal as T, Entity as Tt, LiteralArgs as U, Formula as V, LiteralFilter as W, Term as X, Scalar as Y, AnyRule as Z, Goal as _, Predicate as _t, ArithmeticKind as a, EvidenceMetadata as at, GtGoal as b, PredicateMetadata as bt, ComparisonGoal as c, GroundAtom as ct, DaysBetweenGoal as d, PatternFields as dt, AnyLiteral as et, DivGoal as f, assertAtomLike as ft, FloorToGoal as g, OpenWorldPredicate as gt, FirstOfMonthGoal as h, ClosedWorldPredicate as ht, ArithmeticGoal as i, PositiveLiteral as it, PrimitiveGoal as j, NotGoal as k, RuntimeConstructor as kt, CompoundGoal as l, GroundFields as lt, ExistsGoal as m, fieldEquals as mt, AndGoal as n, LiteralSign as nt, AtomGoal as o, AnyAtom as ot, EqGoal as p, assertGroundAtom as pt, RuleBodyInput as q, AnyAtomGoal as r, NegativeLiteral as rt, CeilToGoal as s, Atom as st, AddGoal as t, Literal as tt, CountGoal as u, NonGroundAtom as ut, GoalExpression as v, PredicateBase as vt, LteGoal as w, Var as wt, GteGoal as x, PredicateWorld as xt, GroundAtomGoal as y, PredicateDeclaration as yt, EqualityTerm as z };

package/dist/{judgment-Cr0JcUt5.d.ts → judgment-v8i3ks5N.d.ts}

@@ -1,4 +1,4 @@
-import { $ as AnyLiteral, A as PrimitiveGoal, Ct as Var, Dt as PredicateSchema, X as AnyRule, Z as Rule, a as ArithmeticKind, et as Literal, g as Goal, l as CompoundGoal, o as AtomGoal, r as AnyAtomGoal, v as GroundAtomGoal } from "./goal-BP745uKh.js";
+import { Ot as PredicateSchema, Q as Rule, Z as AnyRule, _ as Goal, a as ArithmeticKind, et as AnyLiteral, j as PrimitiveGoal, l as CompoundGoal, o as AtomGoal, r as AnyAtomGoal, tt as Literal, wt as Var, y as GroundAtomGoal } from "./goal-BBoSfPUN.js";
 /** Four-valued result for an evaluated proposition or goal. */
 type GoalValue = "false" | "unknown" | "conflicted" | "true";
 /** One variable assignment in scope for an evaluated goal. */

package/dist/kb.d.ts

@@ -1,6 +1,6 @@
-import { $ as AnyLiteral, Dt as PredicateSchema, Q as RuleKind, St as Annotations, U as LiteralFilter, X as AnyRule, Z as Rule, et as Literal, it as EvidenceMetadata, nt as NegativeLiteral, ot as Atom, q as RuleBuilder, rt as PositiveLiteral, st as GroundAtom, tt as LiteralSign, vt as PredicateDeclaration, xt as AnnotationValue } from "./goal-BP745uKh.js";
-import { n as KnowledgeBase, t as EntityRegistry } from "./knowledge-base-Da5HLCsY.js";
-import { _ as QueryAllJudgment, v as QueryJudgment } from "./judgment-Cr0JcUt5.js";
+import { $ as RuleKind, Ct as Annotations, J as RuleBuilder, Ot as PredicateSchema, Q as Rule, St as AnnotationValue, W as LiteralFilter, Z as AnyRule, at as EvidenceMetadata, ct as GroundAtom, et as AnyLiteral, it as PositiveLiteral, nt as LiteralSign, rt as NegativeLiteral, st as Atom, tt as Literal, yt as PredicateDeclaration } from "./goal-BBoSfPUN.js";
+import { n as KnowledgeBase, t as EntityRegistry } from "./knowledge-base-CkU_xzmB.js";
+import { _ as QueryAllJudgment, v as QueryJudgment } from "./judgment-v8i3ks5N.js";
 /** Guarded knowledge-base operations that can be permitted independently. */
 type Operation = "assert" | "deny" | "query";
 /** An effective grant after blocks and duplicates have been removed. */

package/dist/kb.js

@@ -1,5 +1,5 @@
-import { t as ExclusiveDefinitionProgrammerError } from "./programmer-errors-DDfy03Y0.js";
-import { n as queryAll, o as isAtomLike, t as query } from "./query-Dxm7EpxZ.js";
+import { t as ExclusiveDefinitionProgrammerError } from "./programmer-errors-DLE1xWJ_.js";
+import { n as queryAll, o as isAtomLike, t as query } from "./query-CN6EOPwp.js";
 // ../core/src/knowledge-base/assertions/exclusive-definitions.ts
 /** Assert that each predicate has either iff definition semantics or if rule-disjunction semantics, not both. */
 function assertExclusiveDefinitions(rules) {

package/dist/{knowledge-base-Da5HLCsY.d.ts → knowledge-base-CkU_xzmB.d.ts}

@@ -1,4 +1,4 @@
-import { $ as AnyLiteral, Dt as PredicateSchema, H as LiteralArgs, U as LiteralFilter, X as AnyRule, it as EvidenceMetadata, kt as RuntimeType, nt as NegativeLiteral, ot as Atom, q as RuleBuilder, rt as PositiveLiteral, vt as PredicateDeclaration, wt as Entity } from "./goal-BP745uKh.js";
+import { At as RuntimeType, J as RuleBuilder, Ot as PredicateSchema, Tt as Entity, U as LiteralArgs, W as LiteralFilter, Z as AnyRule, at as EvidenceMetadata, et as AnyLiteral, it as PositiveLiteral, rt as NegativeLiteral, st as Atom, yt as PredicateDeclaration } from "./goal-BBoSfPUN.js";
 /** Registry of known domain entities, keyed by constructor and id. */
 declare class EntityRegistry {
   private readonly entitiesByType;

package/dist/{programmer-errors-DDfy03Y0.js → programmer-errors-DLE1xWJ_.js}

@@ -15,13 +15,19 @@ var PrimitiveArithmeticProgrammerError = class extends ProgrammerError {
 	/** The arithmetic goal being evaluated when the failure occurred. */
 	goal;
 	constructor(operation, operands, goal) {
-		super(`${operation} expected ${operation === "daysBetween" || operation === "yearsBetween" ? "date" : "numeric"} operands${operation === "roundTo" || operation === "floorTo" || operation === "ceilTo" ? " and a whole number of decimal places" : ""}`);
+		super(`${operation} expected ${expectedOperands(operation)}`);
 		this.name = "PrimitiveArithmeticProgrammerError";
 		this.operation = operation;
 		this.operands = operands;
 		this.goal = goal;
 	}
 };
+function expectedOperands(operation) {
+	if (operation === "daysBetween" || operation === "yearsBetween") return "date operands";
+	if (operation === "firstOfMonth") return "a whole year and a whole month from 1 to 12";
+	if (operation === "roundTo" || operation === "floorTo" || operation === "ceilTo") return "numeric operands and a whole number of decimal places";
+	return "numeric operands";
+}
 /** Rule body uses variables before any constructive source can bind them. */
 var UnsafeUnboundVariableProgrammerError = class extends ProgrammerError {
 	/** The variables used before any constructive source could bind them. */

package/dist/{query-Dxm7EpxZ.js → query-CN6EOPwp.js}

@@ -1,5 +1,5 @@
-import { a as isVar, i as Var, n as AssertionError, r as assert, t as isFormula } from "./types-0ZvnLf2N.js";
-import { a as UnsafeUnboundVariableProgrammerError, i as UnconstructiveRecursionProgrammerError, n as PrimitiveArithmeticProgrammerError } from "./programmer-errors-DDfy03Y0.js";
+import { a as Var, i as TEMPORARY_PREFIX, n as AssertionError, o as isTemporary, r as assert, s as isVar, t as isFormula } from "./types-DeYyybXd.js";
+import { a as UnsafeUnboundVariableProgrammerError, i as UnconstructiveRecursionProgrammerError, n as PrimitiveArithmeticProgrammerError } from "./programmer-errors-DLE1xWJ_.js";
 // ../core/src/types/atom.ts
 /** Return whether an atom has no logic variables in its fields. */
 function isGroundAtom(atom) {
@@ -85,6 +85,16 @@ function yearsBetween(later, earlier) {
 	const years = later.getUTCFullYear() - earlier.getUTCFullYear();
 	return later.getUTCMonth() * 100 + later.getUTCDate() < earlier.getUTCMonth() * 100 + earlier.getUTCDate() ? years - 1 : years;
 }
+/**
+* The first day of a month at UTC midnight, or undefined unless the year is a whole
+* number a date can hold and the month a whole number from 1 to 12.
+*/
+function firstOfMonth(year, month) {
+	if (!Number.isInteger(year) || !Number.isInteger(month) || month < 1 || month > 12) return;
+	const day = /* @__PURE__ */ new Date(0);
+	day.setUTCFullYear(year, month - 1, 1);
+	return Number.isNaN(day.getTime()) ? void 0 : day;
+}
 // ../core/src/types/goal.ts
 /** Shared runtime classification for arithmetic formulas. */
 const ARITHMETIC_KINDS = [
@@ -94,6 +104,7 @@ const ARITHMETIC_KINDS = [
 	"div",
 	"daysBetween",
 	"yearsBetween",
+	"firstOfMonth",
 	"min",
 	"max",
 	"roundTo",
@@ -1359,7 +1370,7 @@ function evaluateAggregateInto(literals, rules, variable, aggregate, bindings, a
 		}
 	}
 	const existing = valueForVariable(bindings, variable);
-	const target = existing === UNBOUND ? variable : new Var(`$tmp${context.nextTemp++}`);
+	const target = existing === UNBOUND ? variable : new Var(`${TEMPORARY_PREFIX}${context.nextTemp++}`);
 	const nextBindings = new Map(bindings);
 	const values = rows.map((row) => resolveAggregateValue(valueExpression, row.bindings));
 	let value;
@@ -1650,6 +1661,11 @@ function calculateValue(kind, left, right, goal) {
 		case "div": return left / right;
 		case "daysBetween":
 		case "yearsBetween": break;
+		case "firstOfMonth": {
+			const day = firstOfMonth(left, right);
+			if (day === void 0) throw new PrimitiveArithmeticProgrammerError(kind, [left, right], goal);
+			return day;
+		}
 		case "min": return Math.min(left, right);
 		case "max": return Math.max(left, right);
 		case "roundTo":
@@ -1883,16 +1899,11 @@ function bindingsArray(bindings) {
 	return [...bindings.entries()];
 }
 /**
-* The temporaries arithmetic introduces for its intermediate results. They record the
-* computation in the proof tree but are not rule variables, so two environments that
+* Whether the result binds a rule variable the environment does not. Temporaries record
+* the computation in the proof tree but are not rule variables, so two environments that
 * differ only in temporaries are the same environment, and a result that adds only
 * temporaries binds nothing beyond the environment it was evaluated in.
 */
-const TEMPORARY_PREFIX = "$tmp";
-function isTemporary(variable) {
-	return variable.name.startsWith(TEMPORARY_PREFIX);
-}
-/** Whether the result binds a rule variable the environment does not. */
 function bindsBeyond(result, environment) {
 	for (const variable of result.keys()) if (!isTemporary(variable) && !environment.has(variable)) return true;
 	return false;

package/dist/{types-0ZvnLf2N.js → types-DeYyybXd.js}

@@ -18,6 +18,15 @@ var Var = class {
 function isVar(value) {
 	return value instanceof Var;
 }
+/**
+* The prefix of the variables the solver introduces for the intermediate results of
+* arithmetic. No rule names them, so they are not written into explanations.
+*/
+const TEMPORARY_PREFIX = "$tmp";
+/** Return whether the solver introduced the variable for an intermediate result. */
+function isTemporary(variable) {
+	return variable.name.startsWith(TEMPORARY_PREFIX);
+}
 // ../core/src/utils/assert.ts
 var AssertionError = class extends Error {
 	constructor(message = "Assertion failed") {
@@ -34,4 +43,4 @@ function assert(condition, message = "Assertion failed") {
 function isFormula(value, kind) {
 	return typeof value === "object" && value !== null && "kind" in value && "args" in value && (kind === void 0 || value.kind === kind) && Array.isArray(value.args);
 }
-export { isVar as a, Var as i, AssertionError as n, assert as r, isFormula as t };
+export { Var as a, TEMPORARY_PREFIX as i, AssertionError as n, isTemporary as o, assert as r, isVar as s, isFormula as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "factbag",
-  "version": "0.0.0-alpha.5",
+  "version": "0.0.0-alpha.6",
   "keywords": [
     "logic",
     "rules-engine",