factbag 0.0.0-alpha.0

package/dist/core/query/query.d.ts

@@ -0,0 +1,47 @@
+import type { Atom, GroundAtom } from "../types/atom.js";
+import type { KnowledgeBase } from "../knowledge-base/knowledge-base.js";
+import type { QueryAllJudgment, QueryJudgment } from "../types/judgment.js";
+import type { PredicateSchema } from "../types/schema.js";
+/**
+ * Evaluate one grounded atom against a knowledge base.
+ *
+ * @remarks
+ * `query` names exactly one proposition — it is not a first-match shorthand
+ * for {@link queryAll}.
+ *
+ * @returns A four-valued {@link Judgment} — `true`, `false`, `unknown`, or
+ * `conflicted` — carrying the proof-support tree for the winning value.
+ *
+ * @throws {@link ProgrammerError} subclasses when the program shape is
+ * invalid, e.g. rule bodies using unbound variables or unconstructive
+ * recursion.
+ *
+ * @example
+ * ```ts
+ * kb.asserts(passedMedicalSchool({ person: alice }), { source: "registry" });
+ * kb.asserts(hasActiveLicense({ person: alice }), { source: "license_board" });
+ * kb.rule(doctor({ person: P })).iff(
+ *   and(passedMedicalSchool({ person: P }), hasActiveLicense({ person: P })),
+ * );
+ *
+ * const judgment = query(kb, doctor({ person: alice }));
+ * judgment.value; // "true"
+ * ```
+ */
+export declare function query<Schema extends PredicateSchema>(kb: KnowledgeBase, atom: GroundAtom<Schema>): QueryJudgment<Schema>;
+/**
+ * Evaluate an atom pattern against a knowledge base, yielding one judgment
+ * per matching ground atom — zero, one, or many.
+ *
+ * @returns One {@link Judgment} per match, each carrying the variable
+ * bindings that ground the pattern.
+ *
+ * @example
+ * ```ts
+ * for (const judgment of queryAll(kb, doctor({ person: P }))) {
+ *   judgment.value; // "true" | "false" | "unknown" | "conflicted"
+ *   judgment.bindings; // e.g. [[P, alice]]
+ * }
+ * ```
+ */
+export declare function queryAll<Schema extends PredicateSchema>(kb: KnowledgeBase, pattern: Atom<Schema>): QueryAllJudgment<Schema>;

package/dist/core/solver/candidate-search.d.ts

@@ -0,0 +1,12 @@
+import type { Atom, GroundAtom } from "../types/atom.js";
+import type { PredicateDeclaration } from "../types/predicate.js";
+import type { AnyRule } from "../types/rule.js";
+/** Query-local candidate tables. Recursive predicates reach a fixed point together. */
+export declare class CandidateSearch {
+    private readonly groups;
+    private readonly tables;
+    constructor(rules: readonly AnyRule[]);
+    candidates(atom: Atom, seeds: readonly GroundAtom[], derive: () => readonly GroundAtom[]): GroundAtom[];
+    sameComponent(left: PredicateDeclaration, right: PredicateDeclaration): boolean;
+    get isEvaluating(): boolean;
+}

package/dist/core/solver/goal-value.d.ts

@@ -0,0 +1,6 @@
+import type { GoalValue } from "../types/common.js";
+export declare function rankGoalValue(value: GoalValue): 0 | 1 | 2 | 3;
+export declare function minGoalValue(...values: readonly GoalValue[]): GoalValue;
+export declare function maxGoalValue(...values: readonly GoalValue[]): GoalValue;
+export declare function negateGoalValue(value: GoalValue): GoalValue;
+export declare function negateAsFailureGoalValue(value: GoalValue): GoalValue;

package/dist/core/solver/matching.d.ts

@@ -0,0 +1,10 @@
+import type { Atom, GroundAtom } from "../types/atom.js";
+import type { AnyRule, Rule } from "../types/rule.js";
+import type { PredicateSchema } from "../types/schema.js";
+import type { Var } from "../types/variable.js";
+export declare function matchRuleForAtom<Schema extends PredicateSchema>(rule: AnyRule, atom: GroundAtom<Schema>): Readonly<{
+    rule: Rule<Schema, unknown>;
+    bindings: ReadonlyMap<Var, unknown>;
+}> | undefined;
+export declare function matchPattern<Schema extends PredicateSchema>(pattern: Atom<Schema>, atom: GroundAtom<Schema>): ReadonlyMap<Var, unknown> | undefined;
+export declare function groundAtom<Schema extends PredicateSchema>(atom: Atom<Schema>, bindings: ReadonlyMap<Var, unknown>): GroundAtom<Schema>;

package/dist/core/solver/query-validation/constructive-recursion.d.ts

@@ -0,0 +1,3 @@
+import type { PredicateSchema } from "../../types/schema.js";
+import type { QueryValidationContext } from "./context.js";
+export declare function assertConstructiveRecursion<Schema extends PredicateSchema>(context: QueryValidationContext<Schema>): void;

package/dist/core/solver/query-validation/constructive-variable-use.d.ts

@@ -0,0 +1,3 @@
+import type { PredicateSchema } from "../../types/schema.js";
+import type { QueryValidationContext } from "./context.js";
+export declare function assertConstructiveVariableUse<Schema extends PredicateSchema>(context: QueryValidationContext<Schema>): void;

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

@@ -0,0 +1,10 @@
+import type { Atom } from "../../types/atom.js";
+import type { AnyLiteral } from "../../types/literal.js";
+import type { AnyRule } from "../../types/rule.js";
+import type { PredicateSchema } from "../../types/schema.js";
+export type QueryValidationContext<Schema extends PredicateSchema = PredicateSchema> = Readonly<{
+    literals: readonly AnyLiteral[];
+    rules: readonly AnyRule[];
+    atom: Atom<Schema>;
+}>;
+export type QueryValidation = <Schema extends PredicateSchema>(context: QueryValidationContext<Schema>) => void;

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

@@ -0,0 +1 @@
+export { validateQuery } from "./validate-query.js";

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

@@ -0,0 +1,27 @@
+import type { AnyLiteral } from "../../types/literal.js";
+import type { PredicateDeclaration } from "../../types/predicate.js";
+import type { AnyRule } from "../../types/rule.js";
+import type { Var } from "../../types/variable.js";
+type EdgeKind = "positive" | "explicit-not" | "closed-world-not" | "aggregate" | "primitive-ungrounded";
+export type Edge = Readonly<{
+    from: PredicateDeclaration;
+    to: PredicateDeclaration;
+    kind: EdgeKind;
+}>;
+export declare function ruleEdges(rule: AnyRule): Edge[];
+export declare function reachablePredicates(start: PredicateDeclaration, edges: readonly Edge[]): Set<PredicateDeclaration>;
+export declare function isNegativeLiteral(value: unknown): value is AnyLiteral & {
+    sign: "-";
+};
+export declare function isAggregateFormula(value: unknown): value is Readonly<{
+    kind: "sum" | "count";
+    args: readonly unknown[];
+}>;
+export declare function isCompleteWhenOption(value: unknown): value is Readonly<{
+    completeWhen: unknown;
+}>;
+export declare function isPrimitiveFormula(value: unknown): boolean;
+export declare function bindVariables(value: unknown, bound: Set<Var>): void;
+export declare function uniqueVariables(variables: readonly Var[]): Var[];
+export declare function variablesIn(value: unknown): Var[];
+export {};

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

@@ -0,0 +1,6 @@
+import type { Atom } from "../../types/atom.js";
+import type { AnyLiteral } from "../../types/literal.js";
+import type { AnyRule } from "../../types/rule.js";
+import type { PredicateSchema } from "../../types/schema.js";
+/** Assert that a query is inside the solver's supported semantic fragment. */
+export declare function validateQuery<Schema extends PredicateSchema>(literals: readonly AnyLiteral[], rules: readonly AnyRule[], atom: Atom<Schema>): void;

package/dist/core/solver/solve-all.d.ts

@@ -0,0 +1,6 @@
+import type { Atom } from "../types/atom.js";
+import type { QueryAllJudgment } from "../types/judgment.js";
+import type { AnyLiteral } from "../types/literal.js";
+import type { AnyRule } from "../types/rule.js";
+import type { PredicateSchema } from "../types/schema.js";
+export declare function solveQueryAll<Schema extends PredicateSchema>(literals: readonly AnyLiteral[], rules: readonly AnyRule[], atom: Atom<Schema>): QueryAllJudgment<Schema>;

package/dist/core/solver/solve.d.ts

@@ -0,0 +1,6 @@
+import type { GroundAtom } from "../types/atom.js";
+import type { AnyLiteral } from "../types/literal.js";
+import type { QueryJudgment } from "../types/judgment.js";
+import type { AnyRule } from "../types/rule.js";
+import type { PredicateSchema } from "../types/schema.js";
+export declare function solveQuery<Schema extends PredicateSchema>(literals: readonly AnyLiteral[], rules: readonly AnyRule[], atom: GroundAtom<Schema>): QueryJudgment<Schema>;

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

@@ -0,0 +1,6 @@
+/** JSON-compatible annotation data carried without interpretation by core. */
+export type AnnotationValue = null | boolean | number | string | readonly AnnotationValue[] | {
+    readonly [key: string]: AnnotationValue;
+};
+/** Application-defined, serializable annotations. */
+export type Annotations = Readonly<Record<string, AnnotationValue>>;

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

@@ -0,0 +1,55 @@
+import type { InferRuntime, PredicateSchema } from "./schema.js";
+import type { Var } from "./variable.js";
+import type { PredicateDeclaration } from "./predicate.js";
+/** An atom whose exact schema has been intentionally erased. */
+export type AnyAtom = Readonly<{
+    predicate: PredicateDeclaration;
+    fields: Readonly<Record<string, unknown>>;
+}>;
+/** Static groundedness state carried by an atom type. */
+type AtomState = "ground" | "non-ground";
+/** Field values for a fully grounded atom: no logic variables are present. */
+export type GroundFields<Schema extends PredicateSchema = PredicateSchema> = Readonly<{
+    [Name in keyof Schema]: InferRuntime<Schema[Name]>;
+}>;
+/** Field values for a pattern atom: concrete values or logic variables. */
+export type PatternFields<Schema extends PredicateSchema = PredicateSchema> = Readonly<{
+    [Name in keyof Schema]: InferRuntime<Schema[Name]> | Var;
+}>;
+/** Resolve the field map type for an atom based on its groundedness state. */
+type AtomFields<Schema extends PredicateSchema, State extends AtomState> = State extends "ground" ? GroundFields<Schema> : PatternFields<Schema>;
+/** Shared atom representation parameterized by schema and groundedness. */
+type AtomForState<Schema extends PredicateSchema, State extends AtomState> = Readonly<{
+    predicate: PredicateDeclaration<Schema>;
+    fields: AtomFields<Schema, State>;
+}>;
+/** An atom whose fields are all concrete runtime values. */
+export type GroundAtom<Schema extends PredicateSchema = PredicateSchema> = AtomForState<Schema, "ground">;
+/** An atom pattern that may contain one or more logic variables. */
+export type NonGroundAtom<Schema extends PredicateSchema = PredicateSchema> = AtomForState<Schema, "non-ground">;
+/** An atom whose groundedness has not yet been narrowed by a runtime guard. */
+export type Atom<Schema extends PredicateSchema = PredicateSchema> = GroundAtom<Schema> | NonGroundAtom<Schema>;
+/** Return whether an atom has no logic variables in its fields. */
+export declare function isGroundAtom<Schema extends PredicateSchema>(atom: Atom<Schema>): atom is GroundAtom<Schema>;
+/** Assert that an atom has no logic variables in its fields. */
+export declare function assertGroundAtom<Schema extends PredicateSchema>(atom: Atom<Schema>): asserts atom is GroundAtom<Schema>;
+/** Return whether an unknown value has the runtime shape of an atom. */
+export declare function isAtomLike(value: unknown): value is AnyAtom;
+/** Assert that an unknown value has the runtime shape of an atom. */
+export declare function assertAtomLike(value: unknown): asserts value is AnyAtom;
+/**
+ * Narrow a schema-erased atom to a predicate by declaration identity and field
+ * shape. Identity is the real guarantor: an atom carrying this predicate was
+ * built by its constructor, so its fields already satisfy the schema.
+ */
+export declare function isAtomForPredicate<Schema extends PredicateSchema>(atom: AnyAtom, predicate: PredicateDeclaration<Schema>): atom is Atom<Schema>;
+/** Return whether two atoms have the same predicate and field values. */
+export declare function atomEquals(left: AnyAtom, right: AnyAtom): boolean;
+/**
+ * Return whether two atom field values denote the same thing: entities by
+ * type + id, everything else (primitives, variables) by reference identity.
+ */
+export declare function fieldEquals(left: unknown, right: unknown): boolean;
+/** Canonical JSON-safe token for a field value, for use in string identity keys. */
+export declare function fieldIdentityToken(value: unknown): unknown;
+export {};

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

@@ -0,0 +1,7 @@
+import type { Var } from "./variable.js";
+/** Four-valued result for an evaluated proposition or goal. */
+export type GoalValue = "false" | "unknown" | "conflicted" | "true";
+/** One variable assignment in scope for an evaluated goal. */
+export type Binding = readonly [variable: Var, value: unknown];
+/** Ordered variable assignments in scope for an evaluated goal. */
+export type Bindings = readonly Binding[];

package/dist/core/types/evidence-metadata.d.ts

@@ -0,0 +1,18 @@
+import type { Annotations } from "./annotations.js";
+/**
+ * Provenance metadata attached to accepted evidence literals: `source` names
+ * where the fact came from, `citation` quotes or references the supporting
+ * material, and `justification` records the asserter's stated reason.
+ */
+export type EvidenceMetadata = Readonly<{
+    /** Name of the system or document the fact came from. */
+    source?: string;
+    /** Quotation or reference into the supporting material. */
+    citation?: string;
+    /** The asserter's stated reason for accepting the fact. */
+    justification?: string;
+    /** Named numeric scores; core stores these without combining or interpreting them. */
+    scores?: Readonly<Record<string, number>>;
+    /** Application-specific annotations, retained on supporting evidence in judgments. */
+    annotations?: Annotations;
+}>;

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

@@ -0,0 +1,103 @@
+import type { AnyAtom, Atom, GroundAtom } from "./atom.js";
+import type { PredicateSchema } from "./schema.js";
+import type { Var } from "./variable.js";
+import type { Entity, Scalar, Term } from "../dsl/types.js";
+/** A resolved value or variable used inside normalized rule goals. */
+export type GoalExpression<Value = Scalar | Entity> = Term<Value>;
+/** A normalized atom goal: evaluate an atom's goal value. */
+export type AtomGoal<Schema extends PredicateSchema = PredicateSchema> = Readonly<{
+    readonly kind: "atom";
+    readonly atom: Atom<Schema>;
+}>;
+/** A normalized atom goal whose exact schema has been intentionally erased. */
+export type AnyAtomGoal = Readonly<{
+    readonly kind: "atom";
+    readonly atom: AnyAtom;
+}>;
+/** A normalized atom goal whose atom is fully grounded. */
+export type GroundAtomGoal<Schema extends PredicateSchema = PredicateSchema> = Readonly<{
+    readonly kind: "atom";
+    readonly atom: GroundAtom<Schema>;
+}>;
+/** Require explicit negative support for a goal. */
+export type NotGoal = Readonly<{
+    readonly kind: "not";
+    readonly goal: Goal;
+}>;
+/** Prove every child goal. */
+export type AndGoal = Readonly<{
+    readonly kind: "and";
+    readonly goals: readonly Goal[];
+}>;
+/** Prove at least one child goal. */
+export type OrGoal = Readonly<{
+    readonly kind: "or";
+    readonly goals: readonly Goal[];
+}>;
+/** Existentially quantify variables for a child goal. */
+export type ExistsGoal = Readonly<{
+    readonly kind: "exists";
+    readonly variables: readonly Var[];
+    readonly goal: Goal;
+}>;
+/** Bind a variable to a value before proving a child goal. */
+export type LetGoal = Readonly<{
+    readonly kind: "let";
+    readonly variable: Var;
+    readonly value: GoalExpression;
+    readonly goal: Goal;
+}>;
+/** Arithmetic goal binding the sum of two expressions. */
+export type AddGoal = ArithmeticGoal<"add">;
+/** Arithmetic goal binding the difference of two expressions. */
+export type SubGoal = ArithmeticGoal<"sub">;
+/** Arithmetic goal binding the product of two expressions. */
+export type MulGoal = ArithmeticGoal<"mul">;
+/** Arithmetic goal binding the quotient of two expressions. */
+export type DivGoal = ArithmeticGoal<"div">;
+/** Bind the result of a primitive arithmetic operation. */
+export type ArithmeticGoal<Kind extends "add" | "sub" | "mul" | "div"> = Readonly<{
+    readonly kind: Kind;
+    readonly bind: Var;
+    readonly left: GoalExpression<Scalar>;
+    readonly right: GoalExpression<Scalar>;
+}>;
+/** Comparison goal requiring the operands to be equal. */
+export type EqGoal = ComparisonGoal<"eq">;
+/** Comparison goal requiring the operands to differ. */
+export type NeqGoal = ComparisonGoal<"neq">;
+/** Comparison goal requiring the left operand to be strictly less than the right. */
+export type LtGoal = ComparisonGoal<"lt">;
+/** Comparison goal requiring the left operand to be at most the right. */
+export type LteGoal = ComparisonGoal<"lte">;
+/** Comparison goal requiring the left operand to be strictly greater than the right. */
+export type GtGoal = ComparisonGoal<"gt">;
+/** Comparison goal requiring the left operand to be at least the right. */
+export type GteGoal = ComparisonGoal<"gte">;
+/** Compare two value-producing expressions. */
+export type ComparisonGoal<Kind extends "eq" | "neq" | "lt" | "lte" | "gt" | "gte"> = Readonly<{
+    readonly kind: Kind;
+    readonly left: GoalExpression<Scalar>;
+    readonly right: GoalExpression<Scalar>;
+}>;
+/** Sum a numeric expression over rows matched by a body goal. */
+export type SumGoal = Readonly<{
+    readonly kind: "sum";
+    readonly bind: Var;
+    readonly value: GoalExpression<number | bigint>;
+    readonly where: Goal;
+    readonly completeWhen?: Goal;
+}>;
+/** Count rows matched by a body goal. */
+export type CountGoal = Readonly<{
+    readonly kind: "count";
+    readonly bind: Var;
+    readonly where: Goal;
+    readonly completeWhen?: Goal;
+}>;
+/** A normalized rule-body target that the solver/proof system can evaluate. */
+export type Goal = AnyAtomGoal | NotGoal | AndGoal | OrGoal | ExistsGoal | LetGoal | AddGoal | SubGoal | MulGoal | DivGoal | EqGoal | NeqGoal | LtGoal | LteGoal | GtGoal | GteGoal | SumGoal | CountGoal;
+/** A goal evaluated by recursively evaluating one or more child goals. */
+export type CompoundGoal = NotGoal | AndGoal | OrGoal | ExistsGoal | LetGoal;
+/** A goal evaluated directly by a primitive operator. */
+export type PrimitiveGoal = AddGoal | SubGoal | MulGoal | DivGoal | EqGoal | NeqGoal | LtGoal | LteGoal | GtGoal | GteGoal | SumGoal | CountGoal;

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

@@ -0,0 +1,137 @@
+import type { AnyAtomGoal, AtomGoal, CompoundGoal, Goal, GroundAtomGoal, PrimitiveGoal } from "./goal.js";
+import type { AnyLiteral, Literal } from "./literal.js";
+import type { AnyRule, Rule } from "./rule.js";
+import type { Bindings } from "./common.js";
+import type { PredicateSchema } from "./schema.js";
+/** Support from stored evidence for an atom goal. */
+export type EvidenceSupport<Schema extends PredicateSchema = PredicateSchema> = Readonly<{
+    readonly source: "evidence";
+    readonly literals: readonly Literal<Schema>[];
+}>;
+/** Support from absence in a complete closed-world relation. */
+export type ClosedWorldAbsenceSupport = Readonly<{
+    readonly source: "closed-world-absence";
+}>;
+/** Support from firing a rule for an atom goal. */
+export type RuleSupport<Schema extends PredicateSchema = PredicateSchema> = Readonly<{
+    readonly source: "rule";
+    readonly rule: Rule<Schema, unknown>;
+    readonly body: Judgment;
+}>;
+/** Support from stored evidence after atom schema erasure. */
+export type ErasedEvidenceSupport = Readonly<{
+    readonly source: "evidence";
+    readonly literals: readonly AnyLiteral[];
+}>;
+/** Support from firing a rule after atom schema erasure. */
+export type ErasedRuleSupport = Readonly<{
+    readonly source: "rule";
+    readonly rule: AnyRule;
+    readonly body: Judgment;
+}>;
+/** Support from recursively evaluating child goals of a compound goal. */
+export type SubgoalsSupport = Readonly<{
+    readonly source: "subgoals";
+    readonly judgments: readonly Judgment[];
+}>;
+/** Support from directly evaluating a primitive goal. */
+export type PrimitiveSupport = Readonly<{
+    readonly source: "primitive";
+    readonly evaluation: PrimitiveEvaluation;
+}>;
+/** A variable required by a primitive has no runtime binding on this branch. */
+export type MissingBinding = Readonly<{
+    readonly kind: "missing-binding";
+    readonly variable: unknown;
+}>;
+/** Uniform summary for primitive operations, including aggregates and comparisons. */
+export type PrimitiveEvaluation = Readonly<{
+    readonly operation: string;
+    readonly operands: readonly unknown[];
+    readonly value: "true" | "false" | "unknown" | "conflicted";
+    readonly result?: unknown;
+    readonly results?: Bindings;
+    readonly range?: NumericRange;
+    readonly uncertainty?: readonly PrimitiveUncertainty[];
+}>;
+/** Numeric lower/upper bound produced or consumed by a primitive operation. */
+export type NumericRange = Readonly<{
+    readonly lower: number | bigint;
+    readonly upper: number | bigint | "infinity";
+}>;
+/** Why a primitive evaluation is not exact. */
+export type PrimitiveUncertainty = Readonly<{
+    readonly kind: "conflict";
+    readonly count?: number;
+}> | Readonly<{
+    readonly kind: "unknown";
+    readonly count?: number;
+}> | MissingBinding | Readonly<{
+    readonly kind: "open-world";
+}>;
+/** Support from directly evaluating an arithmetic binding goal. */
+export type ArithmeticPrimitiveSupport = Readonly<{
+    readonly source: "primitive";
+    readonly operands: readonly [left: unknown, right: unknown];
+    readonly results: Bindings;
+}>;
+/** Support from directly evaluating a comparison goal. */
+export type ComparisonPrimitiveSupport = Readonly<{
+    readonly source: "primitive";
+    readonly operands: readonly [left: unknown, right: unknown];
+}>;
+/** Support from directly evaluating a sum aggregate goal. */
+export type SumPrimitiveSupport = Readonly<{
+    readonly source: "primitive";
+    readonly values: readonly unknown[];
+    readonly results: Bindings;
+}>;
+/** Support from directly evaluating a count aggregate goal. */
+export type CountPrimitiveSupport = Readonly<{
+    readonly source: "primitive";
+    readonly matched: number;
+    readonly results: Bindings;
+}>;
+/** Proof support for a primitive goal, narrowed to the support shape for the goal's kind. */
+export type PrimitiveSupportFor<GoalType extends PrimitiveGoal> = PrimitiveSupport | (GoalType["kind"] extends "add" | "sub" | "mul" | "div" ? ArithmeticPrimitiveSupport : GoalType["kind"] extends "eq" | "neq" | "lt" | "lte" | "gt" | "gte" ? ComparisonPrimitiveSupport : GoalType["kind"] extends "sum" ? SumPrimitiveSupport : GoalType["kind"] extends "count" ? CountPrimitiveSupport : never);
+/** Sources of support allowed for a specific goal shape. */
+export type JudgmentSupportFor<GoalType extends Goal> = GoalType extends AtomGoal<infer Schema> ? EvidenceSupport<Schema> | ClosedWorldAbsenceSupport | RuleSupport<Schema> : GoalType extends AnyAtomGoal ? ErasedEvidenceSupport | ClosedWorldAbsenceSupport | ErasedRuleSupport : GoalType extends PrimitiveGoal ? PrimitiveSupportFor<GoalType> : GoalType extends CompoundGoal ? SubgoalsSupport : never;
+/** The evaluated goal and in-scope variable bindings shared by every judgment. */
+export type JudgmentBase<GoalType extends Goal> = Readonly<{
+    readonly goal: GoalType;
+    readonly bindings: Bindings;
+}>;
+/**
+ * Positive and negative supports must match the judgment's goal value.
+ *
+ * `inconclusive` holds derivations that could not settle the value: at atom
+ * goals, rule attempts whose bodies came back unknown; at compound and negated
+ * goals whose value is unknown, the constituent subproofs. Unknown compounds
+ * always carry their subgoals, so an unknown verdict remains traversable down
+ * to the leaf atoms that are actually undetermined.
+ */
+export type Judgment<GoalType extends Goal = Goal> = (JudgmentBase<GoalType> & {
+    readonly value: "true";
+    readonly positive: readonly JudgmentSupportFor<GoalType>[];
+    readonly negative?: never;
+    readonly inconclusive?: readonly JudgmentSupportFor<GoalType>[];
+}) | (JudgmentBase<GoalType> & {
+    readonly value: "false";
+    readonly positive?: never;
+    readonly negative: readonly JudgmentSupportFor<GoalType>[];
+    readonly inconclusive?: readonly JudgmentSupportFor<GoalType>[];
+}) | (JudgmentBase<GoalType> & {
+    readonly value: "conflicted";
+    readonly positive: readonly JudgmentSupportFor<GoalType>[];
+    readonly negative: readonly JudgmentSupportFor<GoalType>[];
+    readonly inconclusive?: readonly JudgmentSupportFor<GoalType>[];
+}) | (JudgmentBase<GoalType> & {
+    readonly value: "unknown";
+    readonly positive?: never;
+    readonly negative?: never;
+    readonly inconclusive?: readonly JudgmentSupportFor<GoalType>[];
+});
+/** Query result for one grounded atom goal. */
+export type QueryJudgment<Schema extends PredicateSchema = PredicateSchema> = Judgment<GroundAtomGoal<Schema>>;
+/** Query-all result containing zero or more grounded atom judgments. */
+export type QueryAllJudgment<Schema extends PredicateSchema = PredicateSchema> = readonly QueryJudgment<Schema>[];

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

@@ -0,0 +1,25 @@
+import type { AnyAtom, Atom } from "./atom.js";
+import type { EvidenceMetadata } from "./evidence-metadata.js";
+import type { PredicateSchema } from "./schema.js";
+/** Evidence polarity for an accepted literal. */
+export type LiteralSign = "+" | "-";
+/** A literal whose exact atom schema has been intentionally erased. */
+export type AnyLiteral = Readonly<{
+    sign: LiteralSign;
+    atom: AnyAtom;
+    metadata?: EvidenceMetadata;
+}>;
+/** Positive support for an atom. */
+export type PositiveLiteral<Schema extends PredicateSchema = PredicateSchema> = Readonly<{
+    sign: "+";
+    atom: Atom<Schema>;
+    metadata?: EvidenceMetadata;
+}>;
+/** Negative support for an atom. */
+export type NegativeLiteral<Schema extends PredicateSchema = PredicateSchema> = Readonly<{
+    sign: "-";
+    atom: Atom<Schema>;
+    metadata?: EvidenceMetadata;
+}>;
+/** A signed atom stored as explicit accepted evidence. */
+export type Literal<Schema extends PredicateSchema = PredicateSchema> = PositiveLiteral<Schema> | NegativeLiteral<Schema>;

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

@@ -0,0 +1,35 @@
+import type { Atom, GroundAtom, GroundFields, PatternFields } from "./atom.js";
+import type { PredicateSchema } from "./schema.js";
+import type { Annotations } from "./annotations.js";
+/** Domain guidance for interpreting a predicate, available to evidence producers. */
+export type PredicateMetadata = Readonly<{
+    description: string;
+    instructions?: string;
+    parameters?: Readonly<Record<string, string>>;
+    annotations?: Annotations;
+}>;
+/** Whether absence of evidence counts as falsity (`closed`) or unknown (`open`). */
+export type PredicateWorld = "open" | "closed";
+/** Predicate metadata carried by atoms and literals. */
+export type PredicateDeclaration<Schema extends PredicateSchema = PredicateSchema> = Readonly<{
+    readonly name: string;
+    readonly params: Schema;
+    readonly paramNames: readonly (keyof Schema & string)[];
+    readonly world: PredicateWorld;
+    readonly metadata?: PredicateMetadata;
+}>;
+/** A callable predicate declaration that constructs schema-typed atoms. */
+export type PredicateBase<Schema extends PredicateSchema = PredicateSchema> = PredicateDeclaration<Schema> & {
+    (fields: GroundFields<Schema>): GroundAtom<Schema>;
+    (fields: PatternFields<Schema>): Atom<Schema>;
+};
+/** A predicate whose unlisted atoms are unknown rather than false. */
+export type OpenWorldPredicate<Schema extends PredicateSchema = PredicateSchema> = PredicateBase<Schema> & {
+    readonly world: "open";
+};
+/** A predicate whose relation is complete: absence of evidence means false. */
+export type ClosedWorldPredicate<Schema extends PredicateSchema = PredicateSchema> = PredicateBase<Schema> & {
+    readonly world: "closed";
+};
+/** Any declared predicate, open- or closed-world. */
+export type Predicate<Schema extends PredicateSchema = PredicateSchema> = OpenWorldPredicate<Schema> | ClosedWorldPredicate<Schema>;

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

@@ -0,0 +1,16 @@
+import type { AnyLiteral, Literal } from "./literal.js";
+import type { PredicateSchema } from "./schema.js";
+/** Rule semantics: `if` states a sufficient condition, `iff` a definition. */
+export type RuleKind = "if" | "iff";
+/** A logical rule with either sufficient or definitional semantics. */
+export type Rule<HeadSchema extends PredicateSchema, Body> = Readonly<{
+    kind: RuleKind;
+    head: Literal<HeadSchema>;
+    body: Body;
+}>;
+/** A rule whose exact head schema and body shape are intentionally erased. */
+export type AnyRule = Readonly<{
+    readonly kind: RuleKind;
+    readonly head: AnyLiteral;
+    readonly body: unknown;
+}>;

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

@@ -0,0 +1,33 @@
+/**
+ * A domain entity carries its own identity: the same type with the same id
+ * is the same entity, however many times it is constructed. Whoever mints
+ * entities owns the uniqueness of ids, exactly like a primary key.
+ */
+export type Entity = Readonly<{
+    id: string;
+}>;
+/** An explicit finite domain of string values for a predicate field. */
+export type EnumType<Value extends string = string> = Readonly<{
+    kind: "enum";
+    values: readonly Value[];
+}>;
+/** Runtime constructor used to validate a predicate field value. */
+export type RuntimeConstructor<T> = (abstract new (...args: never[]) => T) & Readonly<{
+    prototype: T;
+    name: string;
+}>;
+/** Any runtime validator accepted in a predicate schema field. */
+export type RuntimeType<T> = EnumType | RuntimeConstructor<T & Entity> | BigIntConstructor | BooleanConstructor | DateConstructor | NumberConstructor | StringConstructor;
+/** A predicate schema maps field names to runtime validators/constructors. */
+export type PredicateSchema = Readonly<Record<string, BigIntConstructor | BooleanConstructor | DateConstructor | NumberConstructor | StringConstructor | EnumType | ((abstract new (...args: never[]) => Entity) & Readonly<{
+    prototype: Entity;
+    name: string;
+}>)>>;
+/**
+ * Convert a runtime constructor in a predicate schema to its TypeScript value
+ * type. A schema-erased constructor (the bare `RuntimeConstructor<Entity>`)
+ * infers `unknown`, so erased atoms keep permissive field types.
+ */
+export type InferRuntime<T> = T extends EnumType<infer Value> ? Value : T extends StringConstructor ? string : T extends NumberConstructor ? number : T extends BooleanConstructor ? boolean : T extends BigIntConstructor ? bigint : T extends DateConstructor ? Date : T extends {
+    prototype: infer Value;
+} ? RuntimeConstructor<Entity> extends T ? unknown : Value : never;

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

@@ -0,0 +1,13 @@
+/** A logic variable placeholder used in rule heads, rule bodies, and query patterns. */
+export declare class Var<Name extends string = string> {
+    /** Display name used when formatting goals, bindings, and explanations. */
+    readonly name: Name;
+    /**
+     * Create a variable with a display name.
+     *
+     * @throws Error when the name is empty or only whitespace.
+     */
+    constructor(name: Name);
+}
+/** Return whether a runtime value is a logic variable. */
+export declare function isVar(value: unknown): value is Var;

package/dist/core/utils/assert.d.ts

@@ -0,0 +1,4 @@
+export declare class AssertionError extends Error {
+    constructor(message?: string);
+}
+export declare function assert(condition: boolean, message?: string): asserts condition;

package/dist/core/utils/normalize-to-list.d.ts

@@ -0,0 +1,2 @@
+export type OneOrMany<Value> = Value | readonly Value[];
+export declare function normalizeToList<Value>(value: OneOrMany<Value>): readonly Value[];

package/dist/corpus/chunkers.d.ts

@@ -0,0 +1,7 @@
+import type { Chunker, RecursiveChunkOptions } from "./types.js";
+/**
+ * Construct a bounded splitter that prefers paragraph, line, and word boundaries.
+ * Ranges are produced lazily and never split a Unicode grapheme. Custom measures
+ * are checked on exact substrings; a grapheme that cannot fit raises RangeError.
+ */
+export declare function recursive(options: RecursiveChunkOptions): Chunker;