kibi-cli 2.31.0 → 2.32.0

package/dist/operations/proof/claim-bindings.js

@@ -0,0 +1,211 @@
+/*
+ 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 { randomBytes } from "node:crypto";
+import { rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { runOperationJsonQuery, toPrologAtom, } from "../../public/operations/prolog-json.js";
+import { compileWitness, loadSymbol, smtAssertion, } from "./code-certificates.js";
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function text(value) {
+    return typeof value === "string" ? value : "";
+}
+function sorted(values) {
+    return [...new Set(values)].sort();
+}
+function setDifference(code, fact) {
+    const factSet = new Set(fact);
+    const codeSet = new Set(code);
+    const missing = fact.filter((member) => !codeSet.has(member));
+    const extra = code.filter((member) => !factSet.has(member));
+    return [
+        missing.length > 0 ? `missing ${missing.slice(0, 5).join(", ")}` : "",
+        extra.length > 0 ? `not in the set ${extra.slice(0, 5).join(", ")}` : "",
+    ]
+        .filter(Boolean)
+        .join("; ");
+}
+/**
+ * The type-level witness Kibi writes for a typecheck claim binding: it
+ * compiles only when the domain type has exactly the fact's members.
+ */
+// implements REQ-kibi-claim-bound-proofs
+export function setEqualityWitness(importPath, members, membersType) {
+    const union = members.map((member) => JSON.stringify(member)).join(" | ");
+    return [
+        `import type * as domain from ${JSON.stringify(importPath)};`,
+        "type Equals<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;",
+        `type Members = ${membersType};`,
+        `const exact: Equals<Members, ${union}> = true;`,
+        "void exact;",
+        "export {};",
+        "",
+    ].join("\n");
+}
+/**
+ * How a domain export may spell its members as a type: a type alias or
+ * enum, a const array, the values of a string enum, or a const object's keys.
+ */
+function membersTypeCandidates(exportName) {
+    const name = `domain.${exportName}`;
+    return [
+        name,
+        `(typeof ${name})[number]`,
+        `\`\${${name}}\``,
+        `keyof typeof ${name}`,
+    ];
+}
+async function typecheckSetProblem(context, contract, obligation) {
+    const domainId = contract.domain_source?.symbol_id ?? "";
+    const domain = await loadSymbol(context, domainId);
+    if (!domain || domain.sourceFile === "")
+        return `the domain_source symbol ${domainId} has no source file`;
+    const exportName = contract.domain_source?.export ?? domain.title;
+    const directory = path.dirname(domain.sourceFile);
+    const base = path.basename(domain.sourceFile).replace(/\.[cm]?[jt]sx?$/, "");
+    const witnessPath = path.join(directory, `.kibi-claim-witness-${randomBytes(6).toString("hex")}.ts`);
+    const absolute = path.resolve(context.workspaceRoot, witnessPath);
+    let lastReason = "";
+    try {
+        for (const membersType of membersTypeCandidates(exportName)) {
+            writeFileSync(absolute, setEqualityWitness(`./${base}.js`, obligation.members, membersType), "utf8");
+            const compiled = compileWitness(context.workspaceRoot, witnessPath);
+            if (compiled.ok)
+                return null;
+            lastReason = compiled.reason;
+        }
+    }
+    finally {
+        rmSync(absolute, { force: true });
+    }
+    return `${exportName} as a type is not exactly the fact's set {${obligation.members.join(", ")}}${lastReason ? ` (${lastReason.replace(/ the witness \S+/, " the set-equality witness")})` : ""}`;
+}
+function smtNegation(obligation) {
+    const assertion = smtAssertion(obligation.variable, obligation.value_type, {
+        operator: obligation.operator,
+        value: obligation.value,
+    });
+    // (assert X) -> (assert (not X))
+    return `(assert (not ${assertion.slice("(assert ".length, -1)}))`;
+}
+function constraintText(obligation) {
+    return `${obligation.variable} ${obligation.operator} ${obligation.value}`;
+}
+async function derivedProblem(context, contract, certificate, row, coveredBy) {
+    const obligation = record(row.obligation) ?? {};
+    const kind = contract.kind;
+    const factId = row.fact_id ?? "the grounding fact";
+    if (kind === "exhaustive" || kind === "typecheck") {
+        const set = obligation;
+        const domainId = contract.domain_source?.symbol_id ?? "";
+        if (!coveredBy.has(domainId))
+            return `the domain_source symbol ${domainId} is not in the receipt's code scope: link it covered_by the test so a change to the domain stales the proof`;
+        if (kind === "exhaustive") {
+            const members = record(certificate.domain)?.members;
+            const code = sorted(Array.isArray(members) ? members.map((member) => String(member)) : []);
+            const fact = sorted(set.members ?? []);
+            if (code.join("\u0000") !== fact.join("\u0000"))
+                return `the domain members Kibi read are not ${factId}'s set (${setDifference(code, fact)})`;
+            return null;
+        }
+        return typecheckSetProblem(context, contract, set);
+    }
+    const numeric = obligation;
+    if (kind === "arithmetic") {
+        const claim = record(certificate.claim) ?? {};
+        if (text(certificate.variable) !== numeric.variable ||
+            text(certificate.value_type) !== numeric.value_type ||
+            text(claim.operator) !== numeric.operator ||
+            Number(claim.value) !== numeric.value)
+            return `the certificate's claim is not ${factId}'s constraint (${constraintText(numeric)})`;
+        return null;
+    }
+    const query = text(certificate.query).replace(/\s+/g, " ");
+    const negation = smtNegation(numeric);
+    if (!query.includes(negation))
+        return `the query does not assert the negation of ${factId}'s constraint ${negation}`;
+    return null;
+}
+/**
+ * How a certificate binds to each claim its contract names in proves. Kibi
+ * derives what the certificate must establish from each claim's grounding
+ * fact (claim_obligations.pl) and checks the certificate against it; a claim
+ * whose fact has no derivation is only attested by the author. Returns
+ * undefined for a contract that names no claims.
+ */
+// implements REQ-kibi-claim-bound-proofs
+export async function judgeClaimBindings(context, input) {
+    const keys = input.contract.proves ?? [];
+    if (keys.length === 0 || input.contract.kind === undefined)
+        return undefined;
+    if (context.prolog === undefined)
+        return keys.map((key) => ({
+            claim_key: key,
+            binding: "rejected",
+            reason: "no Prolog runtime is attached to resolve the claim",
+        }));
+    const rows = await runOperationJsonQuery(context.prolog, "claim_obligations.pl", `claim_obligations:test_claim_obligations_json(${toPrologAtom(input.testId)}, ${toPrologAtom(JSON.stringify(keys))}, ${toPrologAtom(input.contract.kind)}, JsonString)`, "Claim obligations");
+    const coveredBy = new Set(input.coveredBySymbols);
+    const valueSourced = (input.contract.value_source ?? []).length > 0 &&
+        (input.contract.value_source ?? []).every((source) => coveredBy.has(source.symbol_id));
+    const certificate = record(input.verdict.certificate) ?? {};
+    const bindings = [];
+    for (const row of rows) {
+        const base = {
+            claim_key: row.claim_key,
+            ...(row.requirement_id ? { requirement_id: row.requirement_id } : {}),
+            ...(row.fact_id ? { fact_id: row.fact_id } : {}),
+        };
+        if (row.result === "unresolved" || row.result === "incompatible") {
+            bindings.push({
+                ...base,
+                binding: "rejected",
+                reason: row.reason ?? "the claim cannot be proved by this certificate",
+            });
+            continue;
+        }
+        if (row.result === "attested") {
+            bindings.push({ ...base, binding: "attested", scope: "code" });
+            continue;
+        }
+        const obligation = record(row.obligation) ?? {};
+        if (input.verdict.evidence_level !== "proved") {
+            bindings.push({
+                ...base,
+                binding: "rejected",
+                obligation,
+                reason: `the certificate did not re-check${input.verdict.certificate_rejection ? `: ${input.verdict.certificate_rejection}` : ""}`,
+            });
+            continue;
+        }
+        const problem = await derivedProblem(context, input.contract, certificate, row, coveredBy);
+        const numeric = text(obligation.kind) === "numeric_constraint";
+        bindings.push(problem === null
+            ? {
+                ...base,
+                binding: "derived",
+                scope: numeric && !valueSourced ? "intent" : "code",
+                obligation,
+            }
+            : { ...base, binding: "rejected", obligation, reason: problem });
+    }
+    return bindings;
+}

package/dist/operations/proof/code-certificates.d.ts

@@ -0,0 +1,135 @@
+import type { OperationContext } from "../../public/operations/runtime-types.js";
+import { type ProofContract, type ProofKind } from "../../public/proof-protocol.js";
+/**
+ * What a receipt records about its contract's kind: the evidence level it
+ * supports and, for a certificate kind, the certificate and its re-check.
+ */
+export type CertificateVerdict = Readonly<{
+    kind: ProofKind;
+    evidence_level: "proved" | "tested";
+    certificate?: Readonly<Record<string, unknown>>;
+    certificate_digest?: string;
+    certificate_rejection?: string;
+}>;
+export type SymbolRow = Readonly<{
+    id: string;
+    title: string;
+    sourceFile: string;
+}>;
+export declare function loadSymbol(context: OperationContext, symbolId: string): Promise<SymbolRow | null>;
+export declare function readWorkspaceFile(workspaceRoot: string, relative: string): string | null;
+/**
+ * Whether `source` (at `sourcePath`) imports `targetPath` and names
+ * `identifier`: the domain is read from the code, not hand-listed. A suite
+ * that tests compiled output imports the domain from the TypeScript
+ * project's `outDir`; given the workspace root, such an import counts when it
+ * maps back to the domain's source file under `rootDir`.
+ */
+export declare function importsDomain(source: string, sourcePath: string, targetPath: string, identifier: string, workspaceRoot?: string): boolean;
+/**
+ * Map a workspace-relative path inside a TypeScript project's `outDir` to the
+ * matching path under its `rootDir` (the tsconfig's directory when unset),
+ * using the nearest tsconfig.json above the path. Null when no tsconfig
+ * declares an `outDir` that contains it.
+ */
+export declare function compiledToSourcePath(workspaceRoot: string, relativePath: string): string | null;
+/**
+ * The Python interpreters a domain loads with, most specific first: the
+ * KIBI_PYTHON override, the active virtualenv, a project virtualenv (`.venv`
+ * or `venv`) between the domain file and the workspace root, then python3
+ * and python on PATH. The system interpreter usually cannot import the
+ * project's dependencies, so a project environment comes before it.
+ */
+export declare function pythonDomainInterpreters(workspaceRoot: string, sourceFile: string, env?: NodeJS.ProcessEnv): string[];
+/**
+ * The domain as the code defines it: Kibi imports the domain_source file
+ * itself and reads the named export's members, so a certificate cannot cover
+ * a hand-listed subset. A TypeScript or JavaScript domain loads with bun when
+ * it is on PATH, else with the workspace's tsx, else with node's type
+ * stripping (which retries extensionless relative imports as TypeScript
+ * files); a Python domain (`.py`) loads with the first interpreter
+ * pythonDomainInterpreters finds.
+ */
+export declare function evaluateDomain(workspaceRoot: string, sourceFile: string, exportName: string, options?: Readonly<{
+    /** The TypeScript runners to try, in order (default all three). */
+    runners?: readonly ("bun" | "tsx" | "node")[];
+}>): {
+    ok: true;
+    count: number;
+    members: readonly string[] | null;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * The number a value_source export holds, read the same way as a domain.
+ */
+export declare function evaluateScalar(workspaceRoot: string, sourceFile: string, exportName: string): {
+    ok: true;
+    value: number;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Whether an exhaustive certificate covers the domain Kibi evaluated: the
+ * same members when they are primitive values, else the same count.
+ */
+export declare function domainCoverageProblem(exportName: string, evaluated: Readonly<{
+    count: number;
+    members: readonly string[] | null;
+}>, certified: readonly string[]): string | null;
+/**
+ * Kibi compiles a typecheck witness itself, with the workspace's TypeScript
+ * and fixed strict options (a lax project tsconfig could make the never
+ * check vacuous), and accepts it only with no errors in the witness.
+ */
+export declare function compileWitness(workspaceRoot: string, witnessPath: string): {
+    ok: true;
+    version: string;
+} | {
+    ok: false;
+    reason: string;
+};
+export type FactConstraint = Readonly<{
+    operator: string;
+    value: number;
+}>;
+/** The SMT-LIB assertion a fact constraint must appear as in the query. */
+export declare function smtAssertion(property: string, valueType: "int" | "real", row: FactConstraint): string;
+/**
+ * The values a contract's value_source exports hold, read from the code the
+ * same way as a domain, or why one cannot be read.
+ */
+export declare function valueSourceValues(context: OperationContext, contract: ProofContract): Promise<{
+    ok: true;
+    values: {
+        symbol_id: string;
+        value: number;
+    }[];
+} | {
+    ok: false;
+    reason: string;
+}>;
+/** The solver re-run behind an smt certificate; unsat is the only proof. */
+export declare function rerunSmtQuery(solver: string, query: string): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Re-check the certificate a certificate-kind run left for one test. A
+ * runner kind (e2e, example, property) supports tested evidence and needs
+ * no certificate; a certificate kind supports proved evidence only when the
+ * certificate re-checks: its structure and arithmetic in code_certificates.pl,
+ * and here that the proof read its domain from the code, that the witness is
+ * the workspace file, and that the solver still answers unsat.
+ */
+export declare function checkCodeCertificate(context: OperationContext, input: Readonly<{
+    testId: string;
+    contract: ProofContract;
+    outcome: string;
+    certificate: unknown;
+}>): Promise<CertificateVerdict>;
+//# sourceMappingURL=code-certificates.d.ts.map

package/dist/operations/proof/code-certificates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-certificates.d.ts","sourceRoot":"","sources":["../../../src/operations/proof/code-certificates.ts"],"names":[],"mappings":"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"}