factbag 0.0.0-alpha.0

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

@@ -0,0 +1,196 @@
+import {
+  ExclusiveDefinitionProgrammerError,
+  PrimitiveArithmeticProgrammerError,
+  ProgrammerError,
+  UnsafeUnboundVariableProgrammerError
+} from "../chunk-X3LSDJL4.js";
+import {
+  isAtomLike
+} from "../chunk-4IP7CXNV.js";
+import "../chunk-UVOCOH2I.js";
+
+// src/knowledge-base/assertions/exclusive-definitions.ts
+function assertExclusiveDefinitions(rules) {
+  const rulesByPredicate = /* @__PURE__ */ new Map();
+  for (const rule of rules) {
+    const predicate = rule.head.atom.predicate;
+    const predicateRules = rulesByPredicate.get(predicate) ?? [];
+    predicateRules.push(rule);
+    rulesByPredicate.set(predicate, predicateRules);
+  }
+  for (const [predicate, predicateRules] of rulesByPredicate) {
+    if (predicateRules.some((rule) => rule.kind === "iff") && predicateRules.length > 1) {
+      throw new ExclusiveDefinitionProgrammerError(predicate, predicateRules);
+    }
+  }
+}
+
+// src/knowledge-base/knowledge-base.ts
+var EntityRegistry = class {
+  entitiesByType = /* @__PURE__ */ new Map();
+  /** Register entities so queries can enumerate and resolve them by id. */
+  add(...entities) {
+    for (const entity of entities) {
+      const type = entity.constructor;
+      if (!isEntityConstructor(type)) {
+        continue;
+      }
+      let entitiesById = this.entitiesByType.get(type);
+      if (entitiesById === void 0) {
+        entitiesById = /* @__PURE__ */ new Map();
+        this.entitiesByType.set(type, entitiesById);
+      }
+      entitiesById.set(entity.id, entity);
+    }
+  }
+  /** Look up a registered entity by its type and id. */
+  get(type, id) {
+    if (!isEntityConstructor(type)) {
+      return void 0;
+    }
+    return this.entitiesByType.get(type)?.get(id);
+  }
+  /** List the ids of every registered entity of a type. */
+  ids(type) {
+    if (!isEntityConstructor(type)) {
+      return [];
+    }
+    return [...this.entitiesByType.get(type)?.keys() ?? []];
+  }
+  /** List all registered entities, retaining their original identities. */
+  all() {
+    return [...this.entitiesByType.values()].flatMap((entities) => [...entities.values()]);
+  }
+};
+function isEntityConstructor(type) {
+  return typeof type === "function" && type !== String && type !== Number && type !== Boolean && type !== BigInt && "prototype" in type && typeof type.name === "string";
+}
+var KnowledgeBase = class _KnowledgeBase {
+  /** Registry of known domain entities, used to enumerate closed domains. */
+  entities = new EntityRegistry();
+  storedLiterals = [];
+  storedRules = [];
+  /**
+   * Create an independent store with the same evidence, rules, and registered entities.
+   * Existing records retain their identities; additions and retractions affect only
+   * their own store. This is a structural copy, not a deep clone of domain objects.
+   */
+  fork() {
+    const fork = new _KnowledgeBase();
+    fork.entities.add(...this.entities.all());
+    fork.storedLiterals.push(...this.storedLiterals);
+    fork.storedRules.push(...this.storedRules);
+    return fork;
+  }
+  /**
+   * Accept positive evidence for an atom, returning the stored literal.
+   * Optional {@link EvidenceMetadata} records where the fact came from.
+   *
+   * @example
+   * ```ts
+   * kb.asserts(incomeFact({ person: alice, year: y2024, amountCents: 24_680_000 }), {
+   *   source: "2024_w2",
+   *   citation: "Wages, tips, other compensation: 246,800",
+   * });
+   * ```
+   */
+  asserts(atom, metadata) {
+    const literal = metadata === void 0 ? { sign: "+", atom } : { sign: "+", atom, metadata };
+    this.storedLiterals.push(literal);
+    return literal;
+  }
+  /**
+   * Accept negative evidence for an atom, returning the stored literal. A
+   * denial is explicit counter-evidence — stronger than mere absence.
+   */
+  denies(atom, metadata) {
+    const literal = metadata === void 0 ? { sign: "-", atom } : { sign: "-", atom, metadata };
+    this.storedLiterals.push(literal);
+    return literal;
+  }
+  /**
+   * Start declaring a rule for a head atom; finish with the builder's `if`
+   * (sufficient condition) or `iff` (exclusive definition).
+   *
+   * @throws {@link ExclusiveDefinitionProgrammerError} when the head
+   * predicate ends up with an `iff` definition alongside any other rule.
+   *
+   * @example
+   * ```ts
+   * kb.rule(doctor({ person: P })).iff(
+   *   and(passedMedicalSchool({ person: P }), hasActiveLicense({ person: P })),
+   * );
+   * ```
+   */
+  rule(head) {
+    return {
+      if: (body) => this.addRule(head, "if", body),
+      iff: (body) => this.addRule(head, "iff", body)
+    };
+  }
+  /** Remove previously stored literals, matched by identity. */
+  retract(...literals) {
+    for (const literal of literals) {
+      const index = this.storedLiterals.indexOf(literal);
+      if (index !== -1) {
+        this.storedLiterals.splice(index, 1);
+      }
+    }
+  }
+  /** List stored evidence literals, optionally filtered. */
+  literals(filter) {
+    return filter === void 0 ? [...this.storedLiterals] : this.storedLiterals.filter(filter);
+  }
+  /** List stored rules. */
+  rules() {
+    return [...this.storedRules];
+  }
+  /** Predicates referenced by this KB's facts and rules, in discovery order. */
+  predicates() {
+    const predicates = /* @__PURE__ */ new Set();
+    const visited = /* @__PURE__ */ new Set();
+    function visit(value) {
+      if (typeof value !== "object" || value === null || visited.has(value)) {
+        return;
+      }
+      visited.add(value);
+      if (isAtomLike(value)) {
+        predicates.add(value.predicate);
+        return;
+      }
+      for (const child of Object.values(value)) {
+        visit(child);
+      }
+    }
+    for (const literal of this.storedLiterals) {
+      predicates.add(literal.atom.predicate);
+    }
+    for (const rule of this.storedRules) {
+      predicates.add(rule.head.atom.predicate);
+      visit(rule.body);
+    }
+    return [...predicates];
+  }
+  addRule(head, kind, body) {
+    const rule = { kind, head: { sign: "+", atom: head }, body };
+    this.storedRules.push(rule);
+    try {
+      this.assertValid();
+    } catch (error) {
+      this.storedRules.pop();
+      throw error;
+    }
+    return rule;
+  }
+  assertValid() {
+    assertExclusiveDefinitions(this.storedRules);
+  }
+};
+export {
+  EntityRegistry,
+  ExclusiveDefinitionProgrammerError,
+  KnowledgeBase,
+  PrimitiveArithmeticProgrammerError,
+  ProgrammerError,
+  UnsafeUnboundVariableProgrammerError
+};

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

@@ -0,0 +1,81 @@
+import type { Atom } from "../types/atom.js";
+import type { PredicateDeclaration } from "../types/predicate.js";
+import type { EvidenceMetadata } from "../types/evidence-metadata.js";
+import type { AnyLiteral, NegativeLiteral, PositiveLiteral } from "../types/literal.js";
+import type { Entity, PredicateSchema, RuntimeType } from "../types/schema.js";
+import type { AnyRule } from "../types/rule.js";
+import type { LiteralArgs, LiteralFilter, RuleBuilder } from "../dsl/types.js";
+/** Registry of known domain entities, keyed by constructor and id. */
+export declare class EntityRegistry {
+    private readonly entitiesByType;
+    /** Register entities so queries can enumerate and resolve them by id. */
+    add(...entities: readonly Entity[]): void;
+    /** Look up a registered entity by its type and id. */
+    get(type: RuntimeType<unknown>, id: string): Entity | undefined;
+    /** List the ids of every registered entity of a type. */
+    ids(type: RuntimeType<unknown>): readonly string[];
+    /** List all registered entities, retaining their original identities. */
+    all(): readonly Entity[];
+}
+/**
+ * The store of accepted evidence and derivation rules.
+ *
+ * Evidence enters as signed literals via {@link KnowledgeBase.asserts} and
+ * {@link KnowledgeBase.denies}; rules enter via the fluent
+ * {@link KnowledgeBase.rule} builder. Queries evaluate against this store.
+ */
+export declare class KnowledgeBase {
+    /** Registry of known domain entities, used to enumerate closed domains. */
+    readonly entities: EntityRegistry;
+    private readonly storedLiterals;
+    private readonly storedRules;
+    /**
+     * Create an independent store with the same evidence, rules, and registered entities.
+     * Existing records retain their identities; additions and retractions affect only
+     * their own store. This is a structural copy, not a deep clone of domain objects.
+     */
+    fork(): KnowledgeBase;
+    /**
+     * Accept positive evidence for an atom, returning the stored literal.
+     * Optional {@link EvidenceMetadata} records where the fact came from.
+     *
+     * @example
+     * ```ts
+     * kb.asserts(incomeFact({ person: alice, year: y2024, amountCents: 24_680_000 }), {
+     *   source: "2024_w2",
+     *   citation: "Wages, tips, other compensation: 246,800",
+     * });
+     * ```
+     */
+    asserts<Schema extends PredicateSchema>(atom: Atom<Schema>, metadata?: EvidenceMetadata): PositiveLiteral<Schema>;
+    /**
+     * Accept negative evidence for an atom, returning the stored literal. A
+     * denial is explicit counter-evidence — stronger than mere absence.
+     */
+    denies<Schema extends PredicateSchema>(atom: Atom<Schema>, metadata?: EvidenceMetadata): NegativeLiteral<Schema>;
+    /**
+     * Start declaring a rule for a head atom; finish with the builder's `if`
+     * (sufficient condition) or `iff` (exclusive definition).
+     *
+     * @throws {@link ExclusiveDefinitionProgrammerError} when the head
+     * predicate ends up with an `iff` definition alongside any other rule.
+     *
+     * @example
+     * ```ts
+     * kb.rule(doctor({ person: P })).iff(
+     *   and(passedMedicalSchool({ person: P }), hasActiveLicense({ person: P })),
+     * );
+     * ```
+     */
+    rule<Schema extends PredicateSchema>(head: Atom<Schema>): RuleBuilder<Schema>;
+    /** Remove previously stored literals, matched by identity. */
+    retract<const Literals extends readonly unknown[]>(...literals: Literals & LiteralArgs<Literals>): void;
+    /** List stored evidence literals, optionally filtered. */
+    literals(filter?: LiteralFilter): readonly AnyLiteral[];
+    /** List stored rules. */
+    rules(): readonly AnyRule[];
+    /** Predicates referenced by this KB's facts and rules, in discovery order. */
+    predicates(): readonly PredicateDeclaration[];
+    private addRule;
+    private assertValid;
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Query evaluation: four-valued judgments over ground atoms, carrying full
+ * proof-support trees that record how each value was reached.
+ *
+ * @packageDocumentation
+ */
+export { query, queryAll } from "./query.js";
+export type { Binding, Bindings, GoalValue } from "../types/common.js";
+export type { AddGoal, AndGoal, AnyAtomGoal, ArithmeticGoal, AtomGoal, ComparisonGoal, CompoundGoal, CountGoal, DivGoal, EqGoal, ExistsGoal, Goal, GoalExpression, GroundAtomGoal, GtGoal, GteGoal, LetGoal, LtGoal, LteGoal, MulGoal, NeqGoal, NotGoal, OrGoal, PrimitiveGoal, SubGoal, SumGoal, } from "../types/goal.js";
+export type { ArithmeticPrimitiveSupport, ClosedWorldAbsenceSupport, ComparisonPrimitiveSupport, CountPrimitiveSupport, ErasedEvidenceSupport, ErasedRuleSupport, EvidenceSupport, Judgment, JudgmentBase, JudgmentSupportFor, MissingBinding, NumericRange, PrimitiveEvaluation, PrimitiveSupport, PrimitiveSupportFor, PrimitiveUncertainty, QueryAllJudgment, QueryJudgment, RuleSupport, SubgoalsSupport, SumPrimitiveSupport, } from "../types/judgment.js";