factbag 0.0.0-alpha.0

package/dist/jev/resolve.js

@@ -0,0 +1,99 @@
+import {
+  admissionPolicy,
+  jevAdjudicator
+} from "./chunk-2UXHML67.js";
+
+// src/resolve.ts
+function resolver(corpus, kb, config = {}) {
+  const admission = admissionPolicy(config.admission);
+  const adjudicator = jevAdjudicator(config.client);
+  const output = kb.fork();
+  const jobs = contradictions(output.literals()).flatMap((literals) => {
+    const [first] = literals;
+    if (first === void 0) {
+      return [];
+    }
+    const passages = passagesFor(literals, corpus);
+    let state = "ready";
+    const job = {
+      atom: first.atom,
+      passages,
+      async execute() {
+        if (state !== "ready") {
+          throw new Error(`The contradiction for ${formatAtom(first.atom)} is already ${state}`);
+        }
+        state = "running";
+        try {
+          const answers = await adjudicator.adjudicate({ atom: first.atom, passages });
+          const judgments = answers.map(({ passage, answer }) => {
+            const standing = standingOf(answer, admission);
+            const retracted2 = standing === "RETRACT" ? literals.filter(({ metadata }) => metadata?.source === passage.id) : [];
+            return { passage, standing, answer, retracted: retracted2 };
+          });
+          const retracted = judgments.flatMap(({ retracted: literal }) => literal);
+          output.retract(...retracted);
+          state = "settled";
+          return {
+            atom: first.atom,
+            judgments,
+            kept: literals.filter((literal) => !retracted.includes(literal)),
+            retracted
+          };
+        } catch (error) {
+          state = "ready";
+          throw error;
+        }
+      }
+    };
+    return [job];
+  });
+  return Object.assign(jobs.values(), { kb: output });
+}
+function contradictions(literals) {
+  const identities = /* @__PURE__ */ new Map();
+  const identity = (value) => {
+    if (typeof value === "object" && value !== null || typeof value === "function") {
+      if (value instanceof Date) {
+        return `date:${value.toISOString()}`;
+      }
+      const known = identities.get(value) ?? identities.size;
+      identities.set(value, known);
+      return `ref:${known}`;
+    }
+    return `${typeof value}:${String(value)}`;
+  };
+  const groups = /* @__PURE__ */ new Map();
+  for (const literal of literals) {
+    const { predicate, fields } = literal.atom;
+    const key = [predicate, ...predicate.paramNames.map((name) => fields[name])].map(identity).join("|");
+    groups.set(key, [...groups.get(key) ?? [], literal]);
+  }
+  return [...groups.values()].filter(
+    (group) => group.some(({ sign }) => sign === "+") && group.some(({ sign }) => sign === "-")
+  );
+}
+function passagesFor(literals, corpus) {
+  const passages = /* @__PURE__ */ new Map();
+  for (const { atom, metadata } of literals) {
+    const source = metadata?.source;
+    if (source === void 0) {
+      throw new Error(`Cannot resolve ${formatAtom(atom)}: evidence without a source`);
+    }
+    const { chunk } = corpus.resolve(source);
+    passages.set(chunk.id, chunk);
+  }
+  return [...passages.values()];
+}
+function formatAtom({ predicate, fields }) {
+  const values = predicate.paramNames.map((name) => {
+    const value = fields[name];
+    return typeof value === "object" && value !== null && "id" in value ? String(value.id) : String(value);
+  });
+  return `${predicate.name}(${values.join(", ")})`;
+}
+function standingOf({ probabilities }, policy) {
+  return probabilities.RETRACT >= policy.minimumProbability && probabilities.RETRACT - probabilities.KEEP > policy.ambiguityMargin ? "RETRACT" : "KEEP";
+}
+export {
+  resolver
+};

package/dist/jev/tools.d.ts

@@ -0,0 +1,9 @@
+import type { GuardedKB } from "../guards/index.js";
+import type { Tool } from "./types.js";
+/**
+ * Validate all exposed predicates before any corpus traversal or remote requests,
+ * and enumerate each one's candidates once against the KB. A predicate with more
+ * candidates than one request may carry becomes several tools, each with a slice of
+ * them. Query grants are excluded.
+ */
+export declare function prepareTools(access: GuardedKB): readonly Tool[];

package/dist/jev/types.d.ts

@@ -0,0 +1,63 @@
+import type { Entity, EnumType, GroundAtom, PredicateDeclaration, RuntimeConstructor } from "../core/dsl/index.js";
+import type { Operation } from "../guards/index.js";
+import type { ChoiceResponse, JsonValue } from "@typesafe-ai/sdk";
+/**
+ * Field domains accepted after registration. Open-ended scalar constructors are excluded.
+ *
+ * @beta
+ */
+export type SupportedField = BooleanConstructor | EnumType | RuntimeConstructor<Entity>;
+/**
+ * A predicate refined during registration to supported finite field domains.
+ *
+ * @beta
+ */
+export type SupportedPredicate = PredicateDeclaration<Readonly<Record<string, SupportedField>>>;
+/** A permitted effect on a validated predicate: any guarded operation that writes. */
+export type Action = Exclude<Operation, "query">;
+/**
+ * Interpretations of a passage's relationship to one complete fact.
+ *
+ * @beta
+ */
+export type Outcome = "ASSERT" | "DENY" | "IRRELEVANT";
+/**
+ * Validated response retaining the full three-way distribution.
+ *
+ * @beta
+ */
+export type EvidenceChoice = ChoiceResponse<Record<Outcome, string>>;
+/** One ground atom the model is asked about, with its fields encoded for the request. */
+export type Candidate = Readonly<{
+    id: string;
+    atom: GroundAtom;
+    fields: Record<string, JsonValue>;
+}>;
+/** Everything needed to classify one validated predicate, fixed at run start. */
+export type Tool = Readonly<{
+    predicate: SupportedPredicate;
+    actions: ReadonlySet<Action>;
+    candidates: readonly Candidate[];
+}>;
+/** A validated model response for one tool and chunk; nothing has been written yet. */
+export type ToolResult = Readonly<{
+    tool: Tool;
+    /** The chunk id the answers were given for. */
+    source: string;
+    answers: readonly Readonly<{
+        candidate: Candidate;
+        answer: EvidenceChoice;
+    }>[];
+}>;
+/**
+ * Whether one passage's evidence survives, judged against the passages it conflicts with.
+ *
+ * @beta
+ */
+export type Standing = "KEEP" | "RETRACT";
+/**
+ * Validated response retaining the full distribution.
+ *
+ * @beta
+ */
+export type StandingChoice = ChoiceResponse<Record<Standing, string>>;

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "factbag",
+  "version": "0.0.0-alpha.0",
+  "keywords": [
+    "logic",
+    "rules-engine",
+    "knowledge-base",
+    "explainability",
+    "typescript"
+  ],
+  "bugs": {
+    "url": "https://github.com/factbag/factbag/issues"
+  },
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "type": "module",
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": "^22.18.0 || ^24.0.0 || ^26.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Explainable fact and rule evaluation, document provenance, permission controls, and Jev integration.",
+  "homepage": "https://github.com/factbag/factbag/tree/main/packages/factbag#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/factbag/factbag.git",
+    "directory": "packages/factbag"
+  },
+  "exports": {
+    "./dsl": {
+      "types": "./dist/core/dsl/index.d.ts",
+      "import": "./dist/core/dsl/index.js"
+    },
+    "./kb": {
+      "types": "./dist/core/knowledge-base/index.d.ts",
+      "import": "./dist/core/knowledge-base/index.js"
+    },
+    "./query": {
+      "types": "./dist/core/query/index.d.ts",
+      "import": "./dist/core/query/index.js"
+    },
+    "./explain": {
+      "types": "./dist/core/explanation/index.d.ts",
+      "import": "./dist/core/explanation/index.js"
+    },
+    "./corpus": {
+      "types": "./dist/corpus/index.d.ts",
+      "import": "./dist/corpus/index.js"
+    },
+    "./guards": {
+      "types": "./dist/guards/index.d.ts",
+      "import": "./dist/guards/index.js"
+    },
+    "./jev/classifier": {
+      "types": "./dist/jev/classifier.d.ts",
+      "import": "./dist/jev/classifier.js"
+    },
+    "./jev/errors": {
+      "types": "./dist/jev/errors.d.ts",
+      "import": "./dist/jev/errors.js"
+    },
+    "./jev/resolve": {
+      "types": "./dist/jev/resolve.d.ts",
+      "import": "./dist/jev/resolve.js"
+    }
+  },
+  "devDependencies": {
+    "@factbag/core": "0.1.0-next.0",
+    "@factbag/corpus": "0.1.0-next.0",
+    "@factbag/guards": "0.1.0-next.0",
+    "@factbag/jev": "0.1.0-next.0",
+    "@typesafe-ai/sdk": "0.6.0"
+  },
+  "peerDependencies": {
+    "@typesafe-ai/sdk": "^0.6.0"
+  },
+  "peerDependenciesMeta": {
+    "@typesafe-ai/sdk": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-public-package.ts"
+  }
+}