factbag 0.0.0-alpha.0

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

@@ -0,0 +1,30 @@
+import type { AggregateBuilder, NumericTerm, Term } from "../types.js";
+/**
+ * Sum a numeric term over the rows matched by the aggregate body. Complete
+ * the aggregate with `.where(body)` or `.where(body, { completeWhen })`.
+ *
+ * @remarks
+ * `completeWhen` attaches a completeness condition to the aggregate: while
+ * the condition is unmet, a below-threshold total stays unknown instead of
+ * collapsing to false, since more rows may still arrive.
+ *
+ * @example
+ * ```ts
+ * kb.rule(annualIncomeOver200k({ person: P, year: Y })).iff(
+ *   letIn(
+ *     Total,
+ *     sum(Amount).where(incomeFact({ person: P, year: Y, amountCents: Amount }), {
+ *       completeWhen: incomeReviewComplete({ person: P, year: Y }),
+ *     }),
+ *     gt(Total, 20_000_000),
+ *   ),
+ * );
+ * ```
+ */
+export declare function sum(value: NumericTerm): AggregateBuilder<number | bigint>;
+/**
+ * Count the rows matched by the aggregate body. Runs through the same
+ * aggregate machinery as {@link sum}, but thresholds the number of matching
+ * rows rather than a value total.
+ */
+export declare function count(value: Term): AggregateBuilder;

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

@@ -0,0 +1,27 @@
+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]>;
+/**
+ * Subtract a numeric duration in milliseconds from a date term, producing a
+ * date expression.
+ *
+ * @example
+ * ```ts
+ * // The visit must fall within the 14 days before consent.
+ * kb.rule(adequatePerformanceStatus({ patient: P, trial: T })).if(
+ *   and(
+ *     consentDate({ patient: P, trial: T, date: ConsentDate }),
+ *     visitDate({ patient: P, date: VisitDate }),
+ *     gte(VisitDate, sub(ConsentDate, 14 * dayMs)),
+ *     lte(VisitDate, ConsentDate),
+ *   ),
+ * );
+ * ```
+ */
+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]>;
+/** 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]>;

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

@@ -0,0 +1,13 @@
+import type { ComparableTerm, Formula } from "../types.js";
+/**
+ * Require the left term to be strictly greater than the right.
+ *
+ * @remarks
+ * Comparisons are side constraints: they gate whether a rule fires but
+ * contribute no proof children of their own.
+ */
+export declare function gt(left: ComparableTerm, right: ComparableTerm): Formula<boolean, readonly [ComparableTerm, ComparableTerm]>;
+/** Require the left term to be greater than or equal to the right. */
+export declare function gte(left: ComparableTerm, right: ComparableTerm): Formula<boolean, readonly [ComparableTerm, ComparableTerm]>;
+/** Require the left term to be less than or equal to the right. */
+export declare function lte(left: ComparableTerm, right: ComparableTerm): Formula<boolean, readonly [ComparableTerm, ComparableTerm]>;

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

@@ -0,0 +1,33 @@
+import type { ClosedWorldPredicate, OpenWorldPredicate, PredicateMetadata } from "../types/predicate.js";
+import type { PredicateSchema } from "../types/schema.js";
+/**
+ * Declare a closed-world predicate with named fields: absence of matching
+ * evidence counts as `false`, and `not(...)` uses negation-as-failure.
+ */
+export declare function closedPredicate<const Schema extends PredicateSchema>(name: string, params: Schema, metadata?: PredicateMetadata): ClosedWorldPredicate<Schema>;
+/**
+ * Declare a predicate with named fields, open-world: absent evidence leaves
+ * queries `unknown` rather than `false` (use {@link closedPredicate} for
+ * closed-world semantics). The returned declaration is callable: calling it
+ * with field values or variables constructs an atom for use in evidence,
+ * rules, and queries.
+ *
+ * @example
+ * ```ts
+ * class Person implements Entity {
+ *   constructor(readonly id: string) {}
+ * }
+ *
+ * const incomeFact = predicate("income_fact", {
+ *   person: Person,
+ *   year: Number,
+ *   amountCents: Number,
+ * });
+ * const alice = new Person("alice");
+ * const Amount = variable("Amount");
+ *
+ * const evidence = incomeFact({ person: alice, year: 2024, amountCents: 24_680_000 });
+ * const pattern = incomeFact({ person: alice, year: 2024, amountCents: Amount });
+ * ```
+ */
+export declare function predicate<const Schema extends PredicateSchema>(name: string, params: Schema, metadata?: PredicateMetadata): OpenWorldPredicate<Schema>;

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

@@ -0,0 +1,59 @@
+import type { Atom } from "../types/atom.js";
+import type { AnyLiteral, Literal } from "../types/literal.js";
+import type { Entity, PredicateSchema } from "../types/schema.js";
+import type { Rule } from "../types/rule.js";
+import type { Var } from "../types/variable.js";
+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;
+/** A concrete value or logic variable used in formulas and examples. */
+export type Term<Value = Scalar | Entity> = Value | Var;
+/**
+ * A rule-body expression descriptor built by the DSL operators (`and`, `or`,
+ * `exists`, `letIn`, arithmetic, comparisons, aggregates) and evaluated by
+ * the solver during query.
+ */
+export type Formula<Value, Args extends readonly unknown[]> = Readonly<{
+    readonly kind: string;
+    readonly args: Args;
+    readonly __valueType?: Value;
+}>;
+/** Return whether an unknown value has the runtime shape of a formula. */
+export declare function isFormula(value: unknown, kind?: string): value is Formula<unknown, readonly unknown[]>;
+export type FormulaArgumentInput<Value> = Value extends Scalar | Entity | Var ? Value : Value extends Atom<infer Schema extends PredicateSchema> ? Atom<Schema> : Value extends Literal<infer Schema extends PredicateSchema> ? Literal<Schema> : Value extends Formula<infer FormulaValue, infer Args> ? Formula<FormulaValue, Args> : never;
+/** Preserve the concrete schema of a valid formula, atom, or literal rule body. */
+export type RuleBodyInput<Body> = Body extends Formula<infer Value, infer Args> ? Formula<Value, Args> : Body extends Atom<infer Schema extends PredicateSchema> ? Atom<Schema> : Body extends Literal<infer Schema extends PredicateSchema> ? Literal<Schema> : never;
+export type RuleBodyArgs<Args extends readonly unknown[]> = {
+    readonly [Index in keyof Args]: RuleBodyInput<Args[Index]>;
+};
+type ExistsArgumentInput<Value> = Value extends Var ? Value : RuleBodyInput<Value>;
+export type ExistsArgs<Args extends readonly unknown[]> = {
+    readonly [Index in keyof Args]: ExistsArgumentInput<Args[Index]>;
+};
+/** Preserve a literal's schema while rejecting non-literal arguments. */
+type LiteralInput<Value> = Value extends Literal<infer Schema extends PredicateSchema> ? Literal<Schema> : never;
+/** Validate each literal in a variadic argument list without erasing its schema. */
+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[]>;
+/** 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<{
+    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<{
+        completeWhen: CompleteWhen;
+    }>]>);
+}>;
+/** Rule builder returned by KnowledgeBase.rule(...). */
+export type RuleBuilder<Schema extends PredicateSchema> = Readonly<{
+    if: <const Body>(body: Body & RuleBodyInput<Body>) => Rule<Schema, Body>;
+    iff: <const Body>(body: Body & RuleBodyInput<Body>) => Rule<Schema, Body>;
+}>;

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

@@ -0,0 +1,3 @@
+import { Var } from "../types/variable.js";
+/** Create a logic variable for use in rule heads, rule bodies, and query patterns. */
+export declare function variable<const Name extends string>(name: Name): Var<Name>;

package/dist/core/exceptions/programmer-errors.d.ts

@@ -0,0 +1,36 @@
+import type { ArithmeticGoal } from "../types/goal.js";
+import type { PredicateDeclaration } from "../types/predicate.js";
+import type { AnyRule } from "../types/rule.js";
+import type { Var } from "../types/variable.js";
+/** Base class for errors that mean the caller supplied invalid program logic. */
+export declare class ProgrammerError extends Error {
+    constructor(message: string);
+}
+/** Arithmetic primitive with operands the solver cannot legally evaluate. */
+export declare class PrimitiveArithmeticProgrammerError extends ProgrammerError {
+    /** The arithmetic operation that failed. */
+    readonly operation: "add" | "sub" | "mul" | "div";
+    /** The evaluated left and right operand values. */
+    readonly operands: readonly [unknown, unknown];
+    /** The arithmetic goal being evaluated when the failure occurred. */
+    readonly goal: ArithmeticGoal<"add" | "sub" | "mul" | "div">;
+    constructor(operation: "add" | "sub" | "mul" | "div", operands: readonly [unknown, unknown], goal: ArithmeticGoal<"add" | "sub" | "mul" | "div">);
+}
+/** Rule body uses variables before any constructive source can bind them. */
+export declare class UnsafeUnboundVariableProgrammerError extends ProgrammerError {
+    /** The variables used before any constructive source could bind them. */
+    readonly variables: readonly Var[];
+    constructor(variables: readonly Var[]);
+}
+/** Recursive program structure outside the solver's constructive fragment. */
+export declare class UnconstructiveRecursionProgrammerError extends ProgrammerError {
+    constructor();
+}
+/** Predicate has a complete iff definition and additional competing rules. */
+export declare class ExclusiveDefinitionProgrammerError extends ProgrammerError {
+    /** The predicate holding the exclusive `iff` definition. */
+    readonly predicate: PredicateDeclaration;
+    /** The competing rules that conflict with the `iff` definition. */
+    readonly rules: readonly AnyRule[];
+    constructor(predicate: PredicateDeclaration, rules: readonly AnyRule[]);
+}

package/dist/core/explanation/explain.d.ts

@@ -0,0 +1,20 @@
+import type { Judgment } from "../types/judgment.js";
+import type { Explanation } from "./types.js";
+/**
+ * Convert a judgment's proof-support tree into a compact, LLM-readable
+ * {@link Explanation} of what was concluded and why.
+ *
+ * @example
+ * ```ts
+ * const explanation = explainJudgment(query(kb, doctor({ person: alice })));
+ * ```
+ * Yields nested explanation nodes such as:
+ * ```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" }]
+ * }
+ * ```
+ */
+export declare function explainJudgment(judgment: Judgment): Explanation;

package/dist/core/explanation/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Explanations: convert a query judgment's proof tree into a compact,
+ * LLM-readable claim/because/given structure.
+ *
+ * @packageDocumentation
+ */
+export { explainJudgment } from "./explain.js";
+export type { CompoundExplanation, DerivedExplanation, EvidenceExplanation, EvidenceReason, Explanation, ExplanationBase, TerminalExplanation, } from "./types.js";

package/dist/core/explanation/index.js

@@ -0,0 +1,187 @@
+import {
+  isFormula
+} from "../chunk-YF4PP42K.js";
+import {
+  AssertionError,
+  isVar
+} from "../chunk-UVOCOH2I.js";
+
+// src/explanation/explain.ts
+function explainJudgment(judgment) {
+  if (isClosedWorldAbsence(judgment)) {
+    const atom = judgment.goal.goal.atom;
+    return {
+      claim: claimForJudgment(judgment),
+      because: `${formatAtom(atom)} 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: [explainJudgment(ruleSupport.body)]
+    };
+  }
+  const evidence = supports.flatMap(
+    (support) => support.source === "evidence" ? support.literals : []
+  );
+  if (evidence.length > 0) {
+    const reasons = evidence.map(evidenceReason);
+    const firstReason = reasons[0];
+    return {
+      claim: claimForJudgment(judgment),
+      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(explainJudgment))
+    };
+  }
+  const closedWorldAbsence = supports.find((support) => support.source === "closed-world-absence");
+  if (closedWorldAbsence !== void 0 && judgment.goal.kind === "atom") {
+    return {
+      claim: claimForJudgment(judgment),
+      because: `${formatAtom(judgment.goal.atom)} is closed-world, and no matching evidence is known`
+    };
+  }
+  return {
+    claim: claimForJudgment(judgment),
+    because: "no supporting evidence or rule was found"
+  };
+}
+function uniqueExplanations(explanations) {
+  const seen = /* @__PURE__ */ new Set();
+  const unique = [];
+  for (const explanation of explanations) {
+    const key = JSON.stringify(explanation);
+    if (!seen.has(key)) {
+      seen.add(key);
+      unique.push(explanation);
+    }
+  }
+  return unique;
+}
+function supportsForValue(judgment) {
+  if (judgment.value === "true") {
+    return judgment.positive;
+  }
+  if (judgment.value === "false") {
+    return judgment.negative;
+  }
+  if (judgment.value === "conflicted") {
+    return [...judgment.positive, ...judgment.negative];
+  }
+  return judgment.inconclusive ?? [];
+}
+function isClosedWorldAbsence(judgment) {
+  if (judgment.goal.kind !== "not" || judgment.goal.goal.kind !== "atom") {
+    return false;
+  }
+  if (judgment.value !== "true") {
+    return false;
+  }
+  const [support] = judgment.positive;
+  const [child] = support?.source === "subgoals" ? support.judgments : [];
+  if (child === void 0 || judgment.goal.goal.atom.predicate.world !== "closed") {
+    return false;
+  }
+  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}`;
+}
+function evidenceReason(literal) {
+  const claim = `${formatAtom(literal.atom)} = ${literal.sign === "+" ? "true" : "false"}`;
+  const source = literal.metadata?.source;
+  return source === void 0 ? { claim } : { claim, source };
+}
+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(", ")}`;
+}
+function formatRuleBody(body) {
+  if (isLiteral(body)) {
+    return formatLiteral(body);
+  }
+  if (isAtom(body)) {
+    return formatAtom(body);
+  }
+  if (isFormula(body)) {
+    return `${body.kind}(${body.args.map(formatRuleBody).join(", ")})`;
+  }
+  return formatValue(body);
+}
+function formatLiteral(literal) {
+  return literal.sign === "-" ? `not(${formatAtom(literal.atom)})` : formatAtom(literal.atom);
+}
+function formatGoal(goal) {
+  switch (goal.kind) {
+    case "atom":
+      return formatAtom(goal.atom);
+    case "not":
+      return `not(${formatGoal(goal.goal)})`;
+    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 "add":
+    case "sub":
+    case "mul":
+    case "div":
+      return `${goal.bind.name} = ${goal.kind}(${formatValue(goal.left)}, ${formatValue(goal.right)})`;
+    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)})`;
+    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 formatValue(value) {
+  if (isVar(value)) {
+    return value.name;
+  }
+  if (typeof value === "object" && value !== null && "id" in value && typeof value.id === "string") {
+    return value.id;
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  return String(value);
+}
+function isLiteral(value) {
+  return typeof value === "object" && value !== null && "sign" in value && "atom" in value && (value.sign === "+" || value.sign === "-");
+}
+function isAtom(value) {
+  return typeof value === "object" && value !== null && "predicate" in value && "fields" in value;
+}
+export {
+  explainJudgment
+};

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

@@ -0,0 +1,172 @@
+/** Shared shape for every compact, LLM-readable explanation node. */
+export type ExplanationBase = Readonly<{
+    /** The evaluated claim and its value, e.g. `eligible(alice) = true`. */
+    claim: string;
+}>;
+/**
+ * A compact, LLM-readable explanation node.
+ *
+ * Example intended contents for a derived claim:
+ *
+ * ```json
+ * {
+ *   "claim": "eligible(alice) = true",
+ *   "because": "eligible(P) iff not(active_sanction(P)), with P = alice",
+ *   "given": [
+ *     {
+ *       "claim": "not(active_sanction(alice)) = true",
+ *       "because": "active_sanction(alice) is closed-world, and no evidence is known"
+ *     }
+ *   ]
+ * }
+ * ```
+ */
+export type Explanation = EvidenceExplanation | DerivedExplanation | CompoundExplanation | TerminalExplanation;
+/**
+ * A claim explained directly by accepted evidence.
+ *
+ * Example intended contents for one supporting source:
+ *
+ * ```json
+ * {
+ *   "claim": "active_sanction(bob) = true",
+ *   "because": {
+ *     "source": "sanctions_registry",
+ *     "quote": "Bob appears on the active sanctions list."
+ *   }
+ * }
+ * ```
+ *
+ * Example intended contents for conflicting evidence:
+ *
+ * ```json
+ * {
+ *   "claim": "active_sanction(drew) = conflicted",
+ *   "because": [
+ *     {
+ *       "claim": "active_sanction(drew) = true",
+ *       "source": "sanctions_registry",
+ *       "quote": "Drew appears on the active sanctions list."
+ *     },
+ *     {
+ *       "claim": "active_sanction(drew) = false",
+ *       "source": "appeals_board",
+ *       "quote": "Drew's sanction was overturned on appeal."
+ *     }
+ *   ]
+ * }
+ * ```
+ */
+export type EvidenceExplanation = ExplanationBase & Readonly<{
+    because: EvidenceReason | readonly EvidenceReason[];
+}>;
+/**
+ * A claim explained by applying a rule to subclaims.
+ *
+ * Example intended contents:
+ *
+ * ```json
+ * {
+ *   "claim": "eligible(bob) = false",
+ *   "because": "eligible(P) iff not(active_sanction(P)), with P = bob",
+ *   "given": [
+ *     {
+ *       "claim": "not(active_sanction(bob)) = false",
+ *       "given": [
+ *         {
+ *           "claim": "active_sanction(bob) = true",
+ *           "because": {
+ *             "source": "sanctions_registry",
+ *             "quote": "Bob appears on the active sanctions list."
+ *           }
+ *         }
+ *       ]
+ *     }
+ *   ]
+ * }
+ * ```
+ */
+export type DerivedExplanation = ExplanationBase & Readonly<{
+    because: string;
+    given: readonly Explanation[];
+}>;
+/**
+ * A claim explained by combining subclaims, such as an `and`, `or`, or `not` goal.
+ *
+ * Example intended contents:
+ *
+ * ```json
+ * {
+ *   "claim": "not(active_sanction(drew)) = conflicted",
+ *   "given": [
+ *     {
+ *       "claim": "active_sanction(drew) = conflicted",
+ *       "because": [
+ *         {
+ *           "claim": "active_sanction(drew) = true",
+ *           "source": "sanctions_registry",
+ *           "quote": "Drew appears on the active sanctions list."
+ *         },
+ *         {
+ *           "claim": "active_sanction(drew) = false",
+ *           "source": "appeals_board",
+ *           "quote": "Drew's sanction was overturned on appeal."
+ *         }
+ *       ]
+ *     }
+ *   ]
+ * }
+ * ```
+ */
+export type CompoundExplanation = ExplanationBase & Readonly<{
+    because?: string;
+    given: readonly Explanation[];
+}>;
+/**
+ * A terminal non-evidence explanation, such as closed-world absence or an unknown.
+ *
+ * Example intended contents:
+ *
+ * ```json
+ * {
+ *   "claim": "not(active_sanction(alice)) = true",
+ *   "because": "active_sanction(alice) is closed-world, and no evidence is known"
+ * }
+ * ```
+ */
+export type TerminalExplanation = ExplanationBase & Readonly<{
+    because: string;
+}>;
+/**
+ * Evidence metadata embedded directly under `because`.
+ *
+ * Example intended contents for a single source:
+ *
+ * ```json
+ * {
+ *   "source": "sanctions_registry",
+ *   "quote": "Bob appears on the active sanctions list."
+ * }
+ * ```
+ *
+ * Example intended contents when the evidence reason names its side explicitly:
+ *
+ * ```json
+ * {
+ *   "claim": "active_sanction(drew) = false",
+ *   "source": "appeals_board",
+ *   "quote": "Drew's sanction was overturned on appeal.",
+ *   "metadata": { "reviewed_by": "appeals_panel" }
+ * }
+ * ```
+ */
+export type EvidenceReason = Readonly<{
+    /** Optional when the surrounding `claim` already names what the evidence proves. */
+    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;
+    /** Raw source-specific details that should not be flattened into prose. */
+    metadata?: Readonly<Record<string, unknown>>;
+}>;

package/dist/core/knowledge-base/assertions/exclusive-definitions.d.ts

@@ -0,0 +1,3 @@
+import type { AnyRule } from "../../types/rule.js";
+/** Assert that each predicate has either iff definition semantics or if rule-disjunction semantics, not both. */
+export declare function assertExclusiveDefinitions(rules: readonly AnyRule[]): void;

package/dist/core/knowledge-base/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The knowledge base: store signed evidence literals, declare derivation
+ * rules, and register domain entities.
+ *
+ * @packageDocumentation
+ */
+export { ExclusiveDefinitionProgrammerError, ProgrammerError, PrimitiveArithmeticProgrammerError, UnsafeUnboundVariableProgrammerError, } from "../exceptions/programmer-errors.js";
+export type { EvidenceMetadata } from "../types/evidence-metadata.js";
+export type { Annotations, AnnotationValue } from "../types/annotations.js";
+export type { AnyLiteral, Literal, LiteralSign, NegativeLiteral, PositiveLiteral, } from "../types/literal.js";
+export type { AnyRule, Rule, RuleKind } from "../types/rule.js";
+export type { LiteralFilter, RuleBuilder } from "../dsl/types.js";
+export { EntityRegistry, KnowledgeBase } from "./knowledge-base.js";