kibi-cli 2.32.0 → 2.36.0

package/dist/utils/strict-modeling.js

@@ -226,6 +226,8 @@ export function normalizeSourceKey(value) {
     return normalized;
 }
 function normalizeStableValue(value) {
+    if (Array.isArray(value))
+        return normalizeStableValue([...new Set(value)].sort().join("|"));
     if (typeof value === "string") {
         const normalized = value
             .trim()
@@ -279,8 +281,20 @@ function buildUniqueTags(tags) {
 function buildPropertyFactTitle(normalizedPropertyKey, claim) {
     const label = humanizeKey(normalizedPropertyKey);
     if (claim.operator === "polarity") {
-        return `${label} ${normalizePolarityValue(claim.value) === "forbid" ? "forbidden" : "required"}`;
+        return `${label} ${normalizePolarityValue(scalarValue(claim.value)) === "forbid" ? "forbidden" : "required"}`;
     }
+    if (Array.isArray(claim.value)) {
+        const setLabel = claim.operator === "includes"
+            ? "includes"
+            : claim.operator === "subset_of"
+                ? "within"
+                : claim.operator === "excludes"
+                    ? "excludes"
+                    : "=";
+        return `${label} ${setLabel} ${claim.value.join(", ")}`;
+    }
+    if (claim.operator === "matches")
+        return `${label} matches ${String(claim.value)}`;
     const operatorLabel = claim.operator === "bool"
         ? "="
         : claim.operator === "eq"
@@ -297,19 +311,32 @@ function buildPropertyFactTitle(normalizedPropertyKey, claim) {
     return `${label} ${operatorLabel} ${String(claim.value)}`;
 }
 function buildPropertyFactFields(claim) {
+    // implements REQ-kibi-source-proof-kinds
+    if (Array.isArray(claim.value))
+        return {
+            operator: claim.operator,
+            value_type: "set",
+            value_set: [...new Set(claim.value)].sort(),
+        };
+    if (claim.operator === "matches")
+        return {
+            operator: "matches",
+            value_type: "string",
+            value_string: String(claim.value),
+        };
     if (claim.operator === "polarity") {
         return {
             operator: "eq",
             value_type: "bool",
             value_bool: true,
-            polarity: normalizePolarityValue(claim.value),
+            polarity: normalizePolarityValue(scalarValue(claim.value)),
         };
     }
     if (claim.operator === "bool") {
         return {
             operator: "eq",
             value_type: "bool",
-            value_bool: normalizeBooleanValue(claim.value),
+            value_bool: normalizeBooleanValue(scalarValue(claim.value)),
         };
     }
     return {
@@ -328,7 +355,7 @@ function numericClaimValue(claim) {
         /^\s*-?\d+(?:\.\d+)?\s*$/.test(claim.value)) {
         return Number(claim.value);
     }
-    return claim.value;
+    return scalarValue(claim.value);
 }
 function buildTypedValueFields(value) {
     if (typeof value === "boolean") {
@@ -420,3 +447,9 @@ function buildEntitySourcePath(directory, entityId) {
 export function factSourcePath(factId) {
     return buildEntitySourcePath(resolveEntitySourcePaths().facts, factId);
 }
+/** A claim value as one scalar: a set value joins its members. */
+function scalarValue(value) {
+    return Array.isArray(value)
+        ? value.join("|")
+        : value;
+}

package/dist/workspace-cwd.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Run from a subdirectory of a Kibi workspace against that workspace's KB,
+ * the way git finds its repository: walk up to the nearest directory with
+ * `.kb/manifest.json`. Without this, a command run from `apps/server/`
+ * compiles a second, empty branch store there and reports an empty KB.
+ * An explicit KIBI_WORKSPACE (or alias) and `kibi init` keep the given
+ * directory. Relative path option values keep meaning what the user typed:
+ * the result is the directory to run in and argv with those values made
+ * absolute.
+ */
+export declare function resolveWorkspaceCwd(argv: readonly string[], cwd: string, env: NodeJS.ProcessEnv): Readonly<{
+    cwd: string;
+    argv: string[];
+}>;
+//# sourceMappingURL=workspace-cwd.d.ts.map

package/dist/workspace-cwd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-cwd.d.ts","sourceRoot":"","sources":["../src/workspace-cwd.ts"],"names":[],"mappings":"AAqEA;;;;;;;;;GASG;AAEH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,CAAC,UAAU,GACrB,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAS3C"}

package/dist/workspace-cwd.js

@@ -0,0 +1,86 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+import fs from "node:fs";
+import path from "node:path";
+const WORKSPACE_ENV_KEYS = [
+    "KIBI_WORKSPACE",
+    "KIBI_PROJECT_ROOT",
+    "KIBI_ROOT",
+];
+/** Options whose value is a file or directory the user named from their shell. */
+const PATH_OPTIONS = new Set([
+    "--input",
+    "--output",
+    "--certificates",
+    "--write-certificates",
+]);
+/** Commands that act on the current directory itself, never on an enclosing KB. */
+const CWD_COMMANDS = new Set(["init"]);
+function enclosingKbRoot(start) {
+    let current = path.resolve(start);
+    while (true) {
+        if (fs.existsSync(path.join(current, ".kb", "manifest.json")))
+            return current;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+function absolutePathArgs(argv, base) {
+    const absolute = (value) => value === "-" || path.isAbsolute(value) ? value : path.resolve(base, value);
+    const result = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index] ?? "";
+        const eq = arg.indexOf("=");
+        if (eq > 0 && PATH_OPTIONS.has(arg.slice(0, eq))) {
+            result.push(`${arg.slice(0, eq)}=${absolute(arg.slice(eq + 1))}`);
+            continue;
+        }
+        result.push(arg);
+        const next = argv[index + 1];
+        if (PATH_OPTIONS.has(arg) && next !== undefined && !next.startsWith("--")) {
+            result.push(absolute(next));
+            index += 1;
+        }
+    }
+    return result;
+}
+/**
+ * Run from a subdirectory of a Kibi workspace against that workspace's KB,
+ * the way git finds its repository: walk up to the nearest directory with
+ * `.kb/manifest.json`. Without this, a command run from `apps/server/`
+ * compiles a second, empty branch store there and reports an empty KB.
+ * An explicit KIBI_WORKSPACE (or alias) and `kibi init` keep the given
+ * directory. Relative path option values keep meaning what the user typed:
+ * the result is the directory to run in and argv with those values made
+ * absolute.
+ */
+// implements REQ-cli-subdirectory-workspace
+export function resolveWorkspaceCwd(argv, cwd, env) {
+    const unchanged = { cwd, argv: [...argv] };
+    if (WORKSPACE_ENV_KEYS.some((key) => (env[key] ?? "").trim() !== ""))
+        return unchanged;
+    const command = argv.slice(2).find((arg) => !arg.startsWith("-"));
+    if (command === undefined || CWD_COMMANDS.has(command))
+        return unchanged;
+    const root = enclosingKbRoot(cwd);
+    if (root === null || root === path.resolve(cwd))
+        return unchanged;
+    return { cwd: root, argv: absolutePathArgs(argv, cwd) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cli",
-  "version": "2.32.0",
+  "version": "2.36.0",
   "type": "module",
   "description": "Kibi CLI for knowledge base management",
   "engines": {
@@ -239,7 +239,7 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-core": "^0.24.0",
+    "kibi-core": "^0.26.1",
     "kibi-plugin-builtin": "^0.5.3",
     "kibi-plugin-sdk": "^0.5.0",
     "kibi-swipl": "^1.0.1",

package/schema/validation.pl

@@ -157,6 +157,8 @@ validate_fact_shape(property_value, Props) :-
     valid_operator(Op),
     memberchk(value_type=VT, Props),
     valid_value_type(VT),
+    ( Op == matches -> VT == string ; true ),
+    ( memberchk(Op, [includes, subset_of, excludes]) -> VT == set ; true ),
     exactly_one_value_field(Props),
     value_type_matches_field(VT, Props),
     valid_optional_fact_enums(Props),
@@ -225,7 +227,7 @@ text_atom(Value, Atom) :- atom(Value), !, Atom = Value.
 text_atom(Value, Atom) :- string(Value), atom_string(Atom, Value).
 
 % valid_operator(+Op)
-valid_operator(Op) :- memberchk(Op, [eq, neq, lt, lte, gt, gte]), !.
+valid_operator(Op) :- memberchk(Op, [eq, neq, lt, lte, gt, gte, matches, includes, subset_of, excludes]), !.
 
 % valid_value_type(+VT)
 valid_value_type(ValueType) :- memberchk(ValueType, [string, int, number, bool, set]), !.

package/src/public/operations/evidence-floor.ts

@@ -98,7 +98,7 @@ function suggestionFor(row: EvidenceFloorRow): string {
     return `Run kibi prove for the tests behind ${row.id} so its receipts match the current code, then rerun kibi check --fresh-evidence.`;
   switch (row.requiredEvidence) {
     case "proved":
-      return `Prove every applicable claim of ${row.id}${(row.gapDetails?.unprovedClaims ?? []).length > 0 ? ` (unproved: ${(row.gapDetails?.unprovedClaims ?? []).join(", ")})` : ""}: model each as a set fact (prove it with exhaustive or typecheck) or a numeric fact (arithmetic or smt), name it in a certificate test's proof_contract.proves, and run kibi prove; kibi proof explain ${row.id} shows each claim's bindings. A claim with no such fact can only be attested, so lower required_evidence to tested with the reason in the requirement if that is enough.`;
+      return `Prove every applicable claim of ${row.id}${(row.gapDetails?.unprovedClaims ?? []).length > 0 ? ` (unproved: ${(row.gapDetails?.unprovedClaims ?? []).join(", ")})` : ""}: model each as a set fact (prove it with exhaustive or typecheck), a numeric fact (arithmetic or smt), a rule, predicate or set fact about a predicate (rule or state_machine) or a string fact (regex), name it in a certificate test's proof_contract.proves, and run kibi prove; kibi proof explain ${row.id} shows each claim's bindings. A claim with no such fact can only be attested, so lower required_evidence to tested with the reason in the requirement if that is enough.`;
     case "tested":
       return `Link ${row.id} to a scenario with an end-to-end test that has a proof contract, run kibi prove, and fix its proof gaps (${row.proofGaps.join(", ") || "none listed"}${gapDetailLines(row).length > 0 ? `; ${gapDetailLines(row).join("; ")}` : ""}); kibi proof explain ${row.id} shows each one. Or lower required_evidence if a person decides it does not need tests.`;
     default:

package/src/public/operations/proof-contract-claims.ts

@@ -74,7 +74,7 @@ export function proofContractClaimViolations(
     suggestion:
       issue.claim_key === undefined
         ? `Add proof_contract.proves to ${issue.test_id} with the claim keys (CLAIM-...) of the requirement its certificate establishes; kibi proof explain on the requirement lists its claims.`
-        : `Name a modeled claim of a requirement ${issue.test_id} reaches through its scenarios, grounded by a fact this proof kind can express (a set fact for exhaustive or typecheck, a numeric fact for arithmetic or smt), or remove ${issue.claim_key} from proves.`,
+        : `Name a modeled claim of a requirement ${issue.test_id} reaches through its scenarios, grounded by a fact this proof kind can express (a set fact for exhaustive or typecheck, a numeric fact for arithmetic or smt, a rule, predicate or set fact for rule or state_machine, a string fact for regex), or remove ${issue.claim_key} from proves.`,
     evidence: {
       testId: issue.test_id,
       ...(issue.claim_key === undefined ? {} : { claimKey: issue.claim_key }),

package/src/public/operations/specs/modeling.ts

@@ -55,13 +55,32 @@ export const modelRequirementSpec = {
       },
       operator: {
         type: "string",
-        enum: ["eq", "gt", "gte", "lt", "lte", "neq", "bool", "polarity"],
-        description:
-          "Optional extracted semantic claim operator. Use gt/lt for strict bounds ('greater than zero' is gt 0, not gte 0). Example: 'eq'.",
+        enum: [
+          "eq",
+          "gt",
+          "gte",
+          "lt",
+          "lte",
+          "neq",
+          "bool",
+          "polarity",
+          "matches",
+          "includes",
+          "subset_of",
+          "excludes",
+        ],
+        description:
+          "Optional extracted semantic claim operator. Use gt/lt for strict bounds ('greater than zero' is gt 0, not gte 0). A set claim takes a list value with eq (exactly these), includes (at least these), subset_of (only these) or excludes (none of these); matches takes a regular expression string. Example: 'eq'.",
       },
       value: {
-        description:
-          "Optional extracted semantic claim value. Accepts string, number, or boolean.",
+        anyOf: [
+          { type: "string" },
+          { type: "number" },
+          { type: "boolean" },
+          { type: "array", items: { type: "string" }, minItems: 1 },
+        ],
+        description:
+          "Optional extracted semantic claim value: a string, number or boolean, or a list of strings for a set claim. Example: ['requireAuth'] with operator includes.",
       },
       provenance: {
         type: "string",

package/src/public/operations/specs/mutation-schemas.ts

@@ -244,15 +244,26 @@ export const ENTITY_PROPERTIES_SCHEMA = {
     },
     operator: {
       type: "string",
-      enum: ["eq", "neq", "lt", "lte", "gt", "gte"],
+      enum: [
+        "eq",
+        "neq",
+        "lt",
+        "lte",
+        "gt",
+        "gte",
+        "matches",
+        "includes",
+        "subset_of",
+        "excludes",
+      ],
       description:
-        "Optional comparison operator for property_value facts. Example: 'eq'.",
+        "Optional comparison operator for property_value facts. Example: 'eq'. 'matches' (string facts only): value_string is a JavaScript regular expression (u flag) every value must match as a whole. Set facts only: 'includes' means every member of value_set has the property and other members may have it too; 'subset_of' means every member that has the property is in value_set ('every env var the server reads is one of ...'); 'excludes' means no member of value_set has it ('never imports md5'); 'eq' on a set means exactly those members.",
     },
     value_type: {
       type: "string",
       enum: ["string", "int", "number", "bool", "set"],
       description:
-        "Optional typed value discriminator for property_value facts. Pair with exactly one value_string, value_int, value_number, value_bool, or value_set (set: an exact list of allowed values, operator eq or neq); do not use generic value.",
+        "Optional typed value discriminator for property_value facts. Pair with exactly one value_string, value_int, value_number, value_bool, or value_set (set: a list of members, with operator eq, includes, subset_of or excludes); do not use generic value.",
     },
     value_string: {
       type: "string",

package/src/public/proof-certificates.ts

@@ -28,7 +28,16 @@
 import { createHash } from "node:crypto";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
+import { evaluateSourceCode } from "../operations/proof/source-code-readers.js";
 import { CODE_CERTIFICATE_VERSION } from "./proof-protocol.js";
+import {
+  type SourceModel,
+  type SourceSpec,
+  describeSource,
+  readSource,
+} from "./proof-sources.js";
+
+export type { SourceModel, SourceSpec } from "./proof-sources.js";
 
 /** Where `kibi prove` asks a run to leave its certificates. */
 // implements REQ-kibi-code-proof-kinds
@@ -38,7 +47,15 @@ export const PROOF_CERTIFICATES_ENV = "KIBI_PROOF_CERTIFICATES";
 export type CodeCertificate = Readonly<Record<string, unknown>> &
   Readonly<{
     version: typeof CODE_CERTIFICATE_VERSION;
-    kind: "exhaustive" | "typecheck" | "arithmetic" | "smt";
+    kind:
+      | "exhaustive"
+      | "typecheck"
+      | "arithmetic"
+      | "smt"
+      | "rule"
+      | "state_machine"
+      | "regex"
+      | "source";
     test_id: string;
   }>;
 
@@ -250,6 +267,284 @@ export function smtCertificate(input: {
   };
 }
 
+const certificateText = (value: unknown) =>
+  typeof value === "string" ? value : String(value);
+
+/** A finite domain a rule certificate ranges over. */
+// implements REQ-kibi-non-numeric-proof-kinds
+export type RuleDomain = Readonly<{
+  /** The domain's symbol; omit it for a domain the contract reads from a source. */
+  symbolId?: string;
+  members: Iterable<unknown>;
+}>;
+
+/** A predicate the code decides, and the argument types it takes. */
+// implements REQ-kibi-non-numeric-proof-kinds
+export type RulePredicate = Readonly<{
+  symbolId: string;
+  argTypes: readonly string[];
+  decide: (...args: never[]) => boolean | Promise<boolean>;
+}>;
+
+/**
+ * Call every predicate on every combination of its argument domains and
+ * record what the code decides. Import the domains and functions from their
+ * source (never restate them): Kibi evaluates the same exports at ingest and
+ * rejects a certificate whose tables differ, then model checks each claim's
+ * rule, predicate or set fact against the tables.
+ */
+// implements REQ-kibi-non-numeric-proof-kinds
+export async function ruleCertificate(input: {
+  testId: string;
+  domains: Readonly<Record<string, RuleDomain>>;
+  predicates: Readonly<Record<string, RulePredicate>>;
+}): Promise<CodeCertificate> {
+  const values: Record<string, unknown[]> = {};
+  const domains: Record<string, { symbol_id?: string; members: string[] }> = {};
+  for (const [type, domain] of Object.entries(input.domains)) {
+    values[type] = [...domain.members];
+    domains[type] = {
+      ...(domain.symbolId !== undefined ? { symbol_id: domain.symbolId } : {}),
+      members: values[type].map(certificateText),
+    };
+  }
+  const predicates: Record<
+    string,
+    {
+      symbol_id: string;
+      arg_types: string[];
+      rows: { args: string[]; value?: boolean; error?: string }[];
+    }
+  > = {};
+  for (const [name, predicate] of Object.entries(input.predicates)) {
+    const lists = predicate.argTypes.map((type) => {
+      const list = values[type];
+      if (list === undefined)
+        throw new Error(`no domain for argument type ${type} of ${name}`);
+      return list;
+    });
+    const rows: { args: string[]; value?: boolean; error?: string }[] = [];
+    const count = lists.reduce((product, list) => product * list.length, 1);
+    for (let index = 0; index < count; index++) {
+      let rest = index;
+      const tuple: unknown[] = [];
+      for (let position = lists.length - 1; position >= 0; position--) {
+        const list = lists[position] as unknown[];
+        tuple[position] = list[rest % list.length];
+        rest = Math.floor(rest / list.length);
+      }
+      const args = tuple.map(certificateText);
+      try {
+        const value = await (
+          predicate.decide as (...args: unknown[]) => unknown
+        )(...tuple);
+        rows.push(
+          typeof value === "boolean"
+            ? { args, value }
+            : { args, error: `returned ${typeof value}, not a boolean` },
+        );
+      } catch (error) {
+        rows.push({
+          args,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
+    predicates[name] = {
+      symbol_id: predicate.symbolId,
+      arg_types: [...predicate.argTypes],
+      rows,
+    };
+  }
+  return {
+    version: CODE_CERTIFICATE_VERSION,
+    kind: "rule",
+    test_id: input.testId,
+    domains,
+    predicates,
+  };
+}
+
+/** The calls of a rule certificate that threw or returned a non-boolean. */
+// implements REQ-kibi-non-numeric-proof-kinds
+export function failedCalls(certificate: CodeCertificate): string[] {
+  const predicates = (certificate.predicates ?? {}) as Record<
+    string,
+    { rows?: { args: string[]; error?: string }[] }
+  >;
+  return Object.entries(predicates).flatMap(([name, table]) =>
+    (table.rows ?? [])
+      .filter((row) => row.error !== undefined)
+      .map((row) => `${name}(${row.args.join(", ")}): ${row.error}`),
+  );
+}
+
+type Transitions =
+  | ReadonlyMap<unknown, unknown>
+  | Readonly<Record<string, unknown>>
+  | readonly unknown[]
+  | ((state: never, event: never) => unknown);
+
+function nextStates(next: unknown): unknown[] {
+  if (next === null || next === undefined || next === false) return [];
+  if (Array.isArray(next)) return next;
+  if (next instanceof Set) return [...next];
+  if (next instanceof Map) return [...next.values()];
+  if (typeof next === "object") return Object.values(next);
+  return [next];
+}
+
+/**
+ * Record a state machine as the code defines it: a transition table (an
+ * object or Map from each state to its next state, states, or event map; or
+ * a list of [from, to] pairs) or a next-state function called on every state
+ * and event (a throw, null or undefined means no transition). Kibi reads the
+ * same exports at ingest and checks each claim's transitions, reachability,
+ * initial and terminal states against the machine.
+ */
+// implements REQ-kibi-non-numeric-proof-kinds
+export async function stateMachineCertificate(input: {
+  testId: string;
+  symbolId: string;
+  transitions: Transitions;
+  /** For a next-state function: the states and events it is called on. */
+  states?: Iterable<unknown>;
+  events?: Iterable<unknown>;
+  initial?: unknown;
+}): Promise<CodeCertificate> {
+  const states = new Set<string>();
+  const edges = new Map<string, [string, string]>();
+  const edge = (from: unknown, to: unknown) => {
+    const pair: [string, string] = [certificateText(from), certificateText(to)];
+    states.add(pair[0]);
+    states.add(pair[1]);
+    edges.set(pair.join("\u0000"), pair);
+  };
+  const table = input.transitions;
+  if (typeof table === "function") {
+    const events = [...(input.events ?? [])];
+    for (const state of input.states ?? []) {
+      states.add(certificateText(state));
+      for (const event of events) {
+        let next: unknown;
+        try {
+          next = await (table as (state: unknown, event: unknown) => unknown)(
+            state,
+            event,
+          );
+        } catch {
+          continue;
+        }
+        for (const target of nextStates(next)) edge(state, target);
+      }
+    }
+  } else if (Array.isArray(table)) {
+    for (const entry of table as unknown[]) {
+      if (Array.isArray(entry) && entry.length === 2) edge(entry[0], entry[1]);
+      else if (entry !== null && typeof entry === "object")
+        edge((entry as { from: unknown }).from, (entry as { to: unknown }).to);
+    }
+  } else {
+    const entries =
+      table instanceof Map
+        ? [...table.entries()]
+        : Object.entries(table as Record<string, unknown>);
+    for (const [from, next] of entries) {
+      states.add(certificateText(from));
+      for (const target of nextStates(next)) edge(from, target);
+    }
+  }
+  const initial =
+    input.initial === undefined
+      ? undefined
+      : (typeof input.initial === "object" && input.initial !== null
+          ? [...(input.initial as Iterable<unknown>)]
+          : [input.initial]
+        )
+          .map(certificateText)
+          .sort();
+  return {
+    version: CODE_CERTIFICATE_VERSION,
+    kind: "state_machine",
+    test_id: input.testId,
+    machine: {
+      symbol_id: input.symbolId,
+      states: [...states].sort(),
+      transitions: [...edges.values()].sort((a, b) =>
+        a.join("\u0000") < b.join("\u0000") ? -1 : 1,
+      ),
+      ...(initial !== undefined ? { initial } : {}),
+    },
+  };
+}
+
+/**
+ * Record the pattern (a RegExp) or string constant a string claim is about.
+ * Kibi reads the same export at ingest and decides the claim exactly: a
+ * pattern's language against the fact's, or the string against the fact.
+ */
+// implements REQ-kibi-non-numeric-proof-kinds
+export function regexCertificate(input: {
+  testId: string;
+  symbolId: string;
+  value: RegExp | string;
+}): CodeCertificate {
+  return {
+    version: CODE_CERTIFICATE_VERSION,
+    kind: "regex",
+    test_id: input.testId,
+    pattern:
+      typeof input.value === "string"
+        ? { symbol_id: input.symbolId, type: "string", value: input.value }
+        : {
+            symbol_id: input.symbolId,
+            type: "regexp",
+            source: input.value.source,
+            flags: input.value.flags,
+            flavor: "js",
+          },
+  };
+}
+
+/**
+ * The certificate of a source proof. Kibi reads the contract's source
+ * itself at ingest and stores its own read, so the run only names the test
+ * and, optionally, the source (which must be the contract's). A run may also
+ * leave nothing: a passed source proof needs no certificate from the test.
+ */
+// implements REQ-kibi-source-proof-kinds
+export function sourceCertificate(input: {
+  testId: string;
+  source?: SourceSpec;
+}): CodeCertificate {
+  return {
+    version: CODE_CERTIFICATE_VERSION,
+    kind: "source",
+    test_id: input.testId,
+    ...(input.source !== undefined ? { source: input.source } : {}),
+  };
+}
+
+/**
+ * Read a project source the way Kibi does at ingest: the members (and the
+ * tables, objects or routes) of a JSON or YAML file, a glob, an OpenAPI
+ * document, the references the code makes, a data schema, a route table or
+ * a validator. A rule proof whose contract reads a domain from a source
+ * uses this to range its predicates over the same members.
+ */
+// implements REQ-kibi-source-proof-kinds
+export async function readProjectSource(
+  source: SourceSpec,
+  workspaceRoot: string = process.cwd(),
+): Promise<SourceModel> {
+  const read = await readSource(workspaceRoot, source, evaluateSourceCode);
+  if (!read.ok)
+    throw new Error(
+      `Kibi could not read ${describeSource(source)}: ${read.reason}`,
+    );
+  return read.model;
+}
+
 /**
  * Leave the certificate where `kibi prove` reads it. Returns the file written,
  * or null outside a `kibi prove` run.