kibi-cli 2.18.0 → 2.19.0

package/src/public/operations/discovery-executors.ts

@@ -42,6 +42,7 @@ import {
 import {
   OperationJsonDecodeError,
   runOperationJsonQuery,
+  toPrologAtom,
 } from "./prolog-json.js";
 import type { OperationContext, PrologPort } from "./runtime-types.js";
 import type { OperationResult } from "./types.js";
@@ -54,13 +55,87 @@ export type QueryInput = {
   readonly sourceFile?: string;
   readonly limit?: number;
   readonly offset?: number;
+  /** Typed fact filters (fact entities only); see `FACT_KINDS`. */
+  readonly factKind?: string;
+  readonly predicate?: string;
+  readonly namespace?: string;
+  readonly where?: Readonly<Record<string, string>>;
+  readonly args?: readonly (string | null)[];
+  readonly polarity?: "assert" | "deny";
+  readonly scope?: "all" | "current_requirements";
+  readonly distinct?: string;
+  readonly subjectKey?: string;
+  readonly propertyKey?: string;
 };
 
+/** A ready-to-run follow-up call the query suggests. */
+export type QueryNextCall = Readonly<{ call: string; why: string }>;
+
+/**
+ * Typed-fact view of a kb_query answer: which predicate, property or fact
+ * kind was asked, the schema that names its arguments, distinct value counts,
+ * the values that do exist when nothing matched, warnings about the question
+ * itself and the follow-up calls that make sense next.
+ */
+export type FactQueryPayload = Readonly<{
+  mode: "predicate" | "property" | "schemas" | "fact_kind";
+  predicate?: Record<string, unknown>;
+  property?: Record<string, unknown>;
+  factKind?: string;
+  schema?: Record<string, unknown> | null;
+  subjectFacts?: readonly string[];
+  distinct?: Record<string, unknown> | null;
+  suggestions?: Record<string, unknown> | null;
+  warnings: readonly string[];
+  next: readonly QueryNextCall[];
+}>;
+
 export type QueryPayload = {
   readonly entities: readonly Record<string, unknown>[];
   readonly count: number;
+  readonly factQuery?: FactQueryPayload;
+};
+
+export const FACT_KINDS = [
+  "subject",
+  "property_value",
+  "predicate",
+  "predicate_schema",
+  "observation",
+  "meta",
+  "rule",
+  "rule_schema",
+] as const;
+
+/** Which typed filters each question mode reads; any other is refused. */
+const MODE_FILTERS: Record<FactQueryPayload["mode"], ReadonlySet<string>> = {
+  schemas: new Set(["factKind", "predicate", "namespace"]),
+  predicate: new Set([
+    "predicate",
+    "namespace",
+    "where",
+    "args",
+    "polarity",
+    "scope",
+    "distinct",
+  ]),
+  property: new Set(["subjectKey", "propertyKey", "scope"]),
+  fact_kind: new Set(["factKind"]),
 };
 
+const TYPED_FACT_FILTERS = [
+  "factKind",
+  "predicate",
+  "namespace",
+  "where",
+  "args",
+  "polarity",
+  "scope",
+  "distinct",
+  "subjectKey",
+  "propertyKey",
+] as const satisfies readonly (keyof QueryInput)[];
+
 export type SearchInput = {
   readonly query: string;
   readonly type?: string;
@@ -195,6 +270,400 @@ function isStatusPayload(value: unknown): value is StatusPayload {
   );
 }
 
+function hasTypedFactFilters(input: QueryInput): boolean {
+  return TYPED_FACT_FILTERS.some((key) => input[key] !== undefined);
+}
+
+function requireAtomString(value: unknown, field: string): string {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${field} must be a non-empty string.`);
+  }
+  return value.trim();
+}
+
+function requireEnum<T extends string>(
+  value: unknown,
+  field: string,
+  allowed: readonly T[],
+): T {
+  if (typeof value !== "string" || !allowed.includes(value as T)) {
+    throw new Error(`${field} must be one of: ${allowed.join(", ")}.`);
+  }
+  return value as T;
+}
+
+/**
+ * Builds the Prolog argument spec of a predicate question. Named `where`
+ * entries are resolved against the predicate's declared argument names in
+ * Prolog; positional `args` use `null` as a wildcard.
+ */
+// implements REQ-kibi-query-fact-filters
+function predicateArgSpec(input: QueryInput): string {
+  if (input.where !== undefined && input.args !== undefined) {
+    throw new Error(
+      "Use either where (named arguments) or args (positional), not both.",
+    );
+  }
+  if (input.where !== undefined) {
+    if (
+      input.where === null ||
+      typeof input.where !== "object" ||
+      Array.isArray(input.where)
+    ) {
+      throw new Error("where must be an object of argument name to value.");
+    }
+    const pairs = Object.entries(input.where).map(([key, value]) => {
+      const name = requireAtomString(key, "where argument name");
+      const atom = requireAtomString(value, `where.${key}`);
+      return `${toPrologAtom(name)}=${toPrologAtom(atom)}`;
+    });
+    return `where([${pairs.join(",")}])`;
+  }
+  if (input.args !== undefined) {
+    if (!Array.isArray(input.args)) {
+      throw new Error("args must be an array of constants (null = any).");
+    }
+    const entries = input.args.map((value, index) =>
+      value === null || value === "*"
+        ? "'$any'"
+        : toPrologAtom(requireAtomString(value, `args[${index}]`)),
+    );
+    return `[${entries.join(",")}]`;
+  }
+  return "[]";
+}
+
+type FactQueryResponse = Readonly<{
+  mode: FactQueryPayload["mode"];
+  rows: readonly Record<string, unknown>[];
+  count: number;
+  warnings?: readonly string[];
+  predicate?: Record<string, unknown>;
+  property?: Record<string, unknown>;
+  factKind?: string;
+  schema?: Record<string, unknown> | null;
+  subjectFacts?: readonly string[];
+  distinct?: Record<string, unknown> | null;
+  suggestions?: Record<string, unknown> | null;
+}>;
+
+function callText(args: Record<string, unknown>): string {
+  return `kb_query(${JSON.stringify(args)})`;
+}
+
+/**
+ * Every typed answer names the exact call that makes sense next, so an
+ * agent never has to guess the follow-up from the shape of the data.
+ */
+// implements REQ-kibi-query-fact-filters
+function factQueryNext(
+  input: QueryInput,
+  response: FactQueryResponse,
+): QueryNextCall[] {
+  const next: QueryNextCall[] = [];
+  const first = response.rows[0];
+  const firstId = typeof first?.id === "string" ? first.id : undefined;
+  switch (response.mode) {
+    case "predicate": {
+      if (firstId !== undefined) {
+        next.push({
+          call: callText({ id: firstId }),
+          why: "full fact text and relationships of one row",
+        });
+      }
+      const filters = {
+        predicate: input.predicate,
+        ...(input.namespace !== undefined
+          ? { namespace: input.namespace }
+          : {}),
+        ...(input.where !== undefined ? { where: input.where } : {}),
+        ...(input.args !== undefined ? { args: input.args } : {}),
+        ...(input.polarity !== undefined ? { polarity: input.polarity } : {}),
+        ...(input.scope !== undefined ? { scope: input.scope } : {}),
+      };
+      const names = Array.isArray(
+        (response.schema as { argumentNames?: unknown } | null)?.argumentNames,
+      )
+        ? (
+            response.schema as { argumentNames: unknown[] }
+          ).argumentNames.filter(
+            (name): name is string => typeof name === "string",
+          )
+        : [];
+      const bound = new Set(Object.keys(input.where ?? {}));
+      const free = names.filter((name) => !bound.has(name));
+      if (
+        input.distinct === undefined &&
+        response.count > 0 &&
+        free.length > 0
+      ) {
+        const argument = free[free.length - 1] ?? free[0];
+        next.push({
+          call: callText({ ...filters, distinct: argument }),
+          why: `count the distinct values of '${argument}' across these facts`,
+        });
+      }
+      if (
+        response.count === 0 &&
+        response.suggestions &&
+        typeof response.suggestions === "object" &&
+        (response.warnings ?? []).length === 0
+      ) {
+        // Suggest a correction only for an argument whose requested value
+        // does not exist; a key whose value exists is not the cause.
+        for (const [key, values] of Object.entries(response.suggestions)) {
+          if (!Array.isArray(values)) continue;
+          const requested = input.where?.[key];
+          if (requested !== undefined && values.includes(requested)) continue;
+          const value = values[0];
+          if (typeof value === "string") {
+            next.push({
+              call: callText({
+                ...filters,
+                where: { ...(input.where ?? {}), [key]: value },
+              }),
+              why: `'${key}' has no fact with that value; '${value}' is one that exists`,
+            });
+            break;
+          }
+        }
+      }
+      if (next.length === 0) {
+        next.push({
+          call: callText({ factKind: "predicate_schema" }),
+          why: "list the predicates this KB can answer about and their argument names",
+        });
+      }
+      break;
+    }
+    case "property": {
+      if (firstId !== undefined) {
+        next.push({
+          call: callText({ id: firstId }),
+          why: "full fact text and relationships of one row",
+        });
+      }
+      if (input.propertyKey !== undefined) {
+        next.push({
+          call: callText({ subjectKey: input.subjectKey }),
+          why: "every property stated about this subject",
+        });
+      } else if (response.count === 0) {
+        next.push({
+          call: callText({ factKind: "subject" }),
+          why: "list the subject keys that exist",
+        });
+      }
+      break;
+    }
+    case "schemas": {
+      const name = typeof first?.name === "string" ? first.name : undefined;
+      if (name !== undefined) {
+        next.push({
+          call: callText({ predicate: name }),
+          why: "every stored fact of the first listed predicate",
+        });
+      }
+      break;
+    }
+    case "fact_kind": {
+      if (input.factKind === "predicate") {
+        next.push({
+          call: callText({ factKind: "predicate_schema" }),
+          why: "argument names and constants for asking by name",
+        });
+      } else if (input.factKind === "property_value" && first) {
+        const subjectKey =
+          typeof first.subject_key === "string" ? first.subject_key : undefined;
+        if (subjectKey !== undefined) {
+          next.push({
+            call: callText({ subjectKey }),
+            why: "the properties of the first listed subject",
+          });
+        }
+      } else if (firstId !== undefined) {
+        next.push({
+          call: callText({ id: firstId }),
+          why: "full fact text of one row",
+        });
+      }
+      break;
+    }
+  }
+  return next;
+}
+
+function factRowSummary(row: Record<string, unknown>): string {
+  const id = String(row.id ?? "");
+  if (typeof row.name === "string" && Array.isArray(row.args)) {
+    const effect = typeof row.effect === "string" ? ` -> ${row.effect}` : "";
+    const polarity = row.polarity === "deny" ? " [deny]" : "";
+    return `${id}: ${row.name}(${row.args.map(String).join(", ")})${effect}${polarity}`;
+  }
+  if (
+    typeof row.subjectKey === "string" &&
+    typeof row.propertyKey === "string"
+  ) {
+    const unit = typeof row.unit === "string" && row.unit ? ` ${row.unit}` : "";
+    return `${id}: ${row.subjectKey} ${row.propertyKey} ${String(row.operator ?? "")} ${String(row.value ?? "")}${unit}`;
+  }
+  if (typeof row.name === "string" && typeof row.arity === "number") {
+    const names = Array.isArray(row.argumentNames)
+      ? row.argumentNames.map(String).join(", ")
+      : "";
+    return `${row.name}(${names})`;
+  }
+  return `${id} (${String(row.title ?? "")})`;
+}
+
+/**
+ * Typed fact questions run as validated Prolog goals in the discovery module;
+ * the executor never forwards caller-written Prolog.
+ */
+// implements REQ-kibi-query-fact-filters
+async function executeFactQuery(
+  input: QueryInput,
+  context: OperationContext,
+  limit: number,
+  offset: number,
+): Promise<OperationResult<QueryPayload>> {
+  if (input.type !== undefined && input.type !== "fact") {
+    throw new Error(
+      "Typed fact filters (factKind, predicate, subjectKey, ...) apply to type 'fact' only.",
+    );
+  }
+  for (const key of ["id", "tags", "sourceFile"] as const) {
+    if (input[key] !== undefined) {
+      throw new Error(
+        `${key} cannot be combined with typed fact filters; run a separate kb_query.`,
+      );
+    }
+  }
+  const prolog = requireProlog(context);
+  if (
+    !Number.isFinite(limit) ||
+    !Number.isFinite(offset) ||
+    limit < 0 ||
+    offset < 0
+  ) {
+    throw new Error("limit and offset must be non-negative numbers.");
+  }
+  const page = `${Math.trunc(limit)}, ${Math.trunc(offset)}`;
+  const namespace =
+    input.namespace === undefined
+      ? "none"
+      : toPrologAtom(requireAtomString(input.namespace, "namespace"));
+  const mode =
+    input.factKind === "predicate_schema"
+      ? "schemas"
+      : input.predicate !== undefined
+        ? "predicate"
+        : input.subjectKey !== undefined
+          ? "property"
+          : input.factKind !== undefined
+            ? "fact_kind"
+            : undefined;
+  if (mode === undefined) {
+    throw new Error(
+      "Typed fact filters need a predicate, a subjectKey or a factKind; where/args/polarity/distinct/propertyKey refine one of those.",
+    );
+  }
+  const unused = TYPED_FACT_FILTERS.filter(
+    (key) => input[key] !== undefined && !MODE_FILTERS[mode].has(key),
+  );
+  if (unused.length > 0) {
+    throw new Error(
+      `${unused.join(", ")} do${unused.length === 1 ? "es" : ""} not apply to a ${mode} question; allowed with it: ${[...MODE_FILTERS[mode]].join(", ")}.`,
+    );
+  }
+  const scope =
+    input.scope === undefined
+      ? "all"
+      : requireEnum(input.scope, "scope", ["all", "current_requirements"]);
+  const factKind =
+    input.factKind === undefined
+      ? undefined
+      : requireEnum(input.factKind, "factKind", FACT_KINDS);
+  let goal: string;
+  if (mode === "schemas") {
+    goal = `discovery:ask_schemas_json(${namespace}, ${input.predicate === undefined ? "none" : toPrologAtom(requireAtomString(input.predicate, "predicate"))}, ${page}, JsonString)`;
+  } else if (mode === "predicate") {
+    const name = requireAtomString(input.predicate, "predicate");
+    const polarity =
+      input.polarity === undefined
+        ? "none"
+        : toPrologAtom(
+            requireEnum(input.polarity, "polarity", ["assert", "deny"]),
+          );
+    const distinct =
+      input.distinct === undefined
+        ? "none"
+        : toPrologAtom(requireAtomString(input.distinct, "distinct"));
+    goal = `discovery:ask_predicate_json(${namespace}, ${toPrologAtom(name)}, ${predicateArgSpec(input)}, ${polarity}, ${scope}, ${distinct}, ${page}, JsonString)`;
+  } else if (mode === "property") {
+    const subject = requireAtomString(input.subjectKey, "subjectKey");
+    const property =
+      input.propertyKey === undefined
+        ? "none"
+        : toPrologAtom(requireAtomString(input.propertyKey, "propertyKey"));
+    goal = `discovery:ask_property_json(${toPrologAtom(subject)}, ${property}, ${scope}, ${page}, JsonString)`;
+  } else {
+    goal = `discovery:ask_fact_kind_json(${toPrologAtom(factKind)}, ${page}, JsonString)`;
+  }
+  const response = await runOperationJsonQuery<FactQueryResponse>(
+    prolog,
+    "discovery.pl",
+    goal,
+    "Query execution",
+    context.signal,
+  );
+  const rows = Array.isArray(response.rows) ? response.rows : [];
+  const count =
+    typeof response.count === "number" ? response.count : rows.length;
+  const warnings = Array.isArray(response.warnings) ? response.warnings : [];
+  const factQuery: FactQueryPayload = {
+    mode: response.mode,
+    ...(response.predicate ? { predicate: response.predicate } : {}),
+    ...(response.property ? { property: response.property } : {}),
+    ...(response.factKind ? { factKind: response.factKind } : {}),
+    ...(response.schema !== undefined ? { schema: response.schema } : {}),
+    ...(response.subjectFacts ? { subjectFacts: response.subjectFacts } : {}),
+    ...(response.distinct !== undefined ? { distinct: response.distinct } : {}),
+    ...(response.suggestions !== undefined
+      ? { suggestions: response.suggestions }
+      : {}),
+    warnings,
+    next: factQueryNext(input, { ...response, rows, count }),
+  };
+  const subject =
+    response.mode === "predicate"
+      ? `${String(input.predicate)} facts`
+      : response.mode === "property"
+        ? `properties of ${String(input.subjectKey)}`
+        : response.mode === "schemas"
+          ? "predicate schemas"
+          : `${String(factKind)} facts`;
+  const lines = [
+    count === 0
+      ? `No ${subject} matched.`
+      : `${count} ${subject}. Showing ${rows.length} (offset ${offset}, limit ${limit}): ${rows.map(factRowSummary).join("; ")}`,
+    ...(factQuery.distinct && typeof factQuery.distinct === "object"
+      ? [
+          `Distinct ${String((factQuery.distinct as { argument?: unknown }).argument)}: ${JSON.stringify((factQuery.distinct as { values?: unknown }).values ?? [])}`,
+        ]
+      : []),
+    ...(factQuery.suggestions && typeof factQuery.suggestions === "object"
+      ? [`Values that exist: ${JSON.stringify(factQuery.suggestions)}`]
+      : []),
+    ...warnings.map((warning) => `Warning: ${warning}`),
+    ...factQuery.next.map((entry) => `Next: ${entry.call} (${entry.why})`),
+  ];
+  return {
+    content: [{ type: "text", text: lines.join("\n") }],
+    structuredContent: { entities: rows, count, factQuery },
+  };
+}
+
 export async function executeQuery(
   input: QueryInput,
   context: OperationContext,
@@ -203,6 +672,9 @@ export async function executeQuery(
   const { type, id, tags, sourceFile, limit = 100, offset = 0 } = input;
   try {
     validateEntityType(type);
+    if (hasTypedFactFilters(input)) {
+      return await executeFactQuery(input, context, limit, offset);
+    }
     const prolog = requireProlog(context);
     const signal = context.signal;
     const pageInput = {

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

@@ -24,11 +24,22 @@ const ENTITY_TYPES = [
   "fact",
 ] as const;
 
+const FACT_KINDS = [
+  "subject",
+  "property_value",
+  "predicate",
+  "predicate_schema",
+  "observation",
+  "meta",
+  "rule",
+  "rule_schema",
+] as const;
+
 export const querySpec = {
   name: "kb_query",
   cliName: "query",
   description:
-    "Read entities from the KB with filters. Use for discovery and lookup before edits. Do not use for writes. No mutation side effects. Tags filter by metadata tags only, not entity IDs.",
+    "Read entities from the KB with exact filters, or ask typed fact questions. Use for lookup by id, type, tags or sourceFile, and for precise questions about modeled facts: predicate facts by name with named arguments (predicate + where), property facts of a subject (subjectKey + propertyKey), or the catalog of facts of one kind (factKind; 'predicate_schema' lists the predicates you can ask about with their argument names and constants). Typed answers return matching fact rows plus factQuery: the schema used, distinct counts, values that do exist when nothing matched, warnings about the question and the next call to make. Read-only. Tags filter by metadata tags only, not entity IDs.",
   businessInputSchema: {
     type: "object",
     properties: {
@@ -54,6 +65,61 @@ export const querySpec = {
         description:
           "Optional source-file substring filter. Example: 'src/auth/login.ts'. Uses KB source linkage, not file-system scanning.",
       },
+      factKind: {
+        type: "string",
+        enum: FACT_KINDS,
+        description:
+          "Typed fact filter: list facts of one kind with their typed fields. 'predicate_schema' returns the catalog of askable predicates (argument names, constants, fact counts). Example: 'predicate_schema'.",
+      },
+      predicate: {
+        type: "string",
+        description:
+          "Typed fact filter: predicate name to ask about, e.g. 'has_role' or 'permission_rule'. Combine with where for named arguments. Returns every stored fact of that predicate with its arguments, polarity and allow/deny effect.",
+      },
+      namespace: {
+        type: "string",
+        description:
+          "Optional predicate namespace when the same name exists in several. Default: any namespace.",
+      },
+      where: {
+        type: "object",
+        additionalProperties: { type: "string" },
+        description:
+          "Named argument values for predicate, order-free, using the argument names from the predicate's schema. Example: {actor: 'admin', decision: 'allow'}. An unknown name returns a warning with the declared names; no match returns the values that do exist.",
+      },
+      args: {
+        type: "array",
+        items: { type: ["string", "null"] },
+        description:
+          "Positional argument values for predicate when it has no schema; null matches any value. Example: ['admin', null, null, 'allow']. Prefer where.",
+      },
+      polarity: {
+        type: "string",
+        enum: ["assert", "deny"],
+        description:
+          "Optional polarity filter for predicate facts. Default: both.",
+      },
+      scope: {
+        type: "string",
+        enum: ["all", "current_requirements"],
+        description:
+          "Optional: 'current_requirements' keeps only facts a current (not superseded or retired) requirement requires.",
+      },
+      distinct: {
+        type: "string",
+        description:
+          "Optional argument name to count distinct values of across the matching predicate facts, e.g. distinct: 'role' with predicate 'has_role' and where {user: 'alice'} answers how many roles alice has.",
+      },
+      subjectKey: {
+        type: "string",
+        description:
+          "Typed fact filter: dotted subject key whose property facts to list, e.g. 'user.role_assignment'. Combine with propertyKey for one property.",
+      },
+      propertyKey: {
+        type: "string",
+        description:
+          "Optional property key under subjectKey, e.g. 'max_roles'. Returns operator, value and unit of each fact.",
+      },
       limit: {
         type: "number",
         default: 100,

package/src/public/skills/kibi-usage/SKILL.md

@@ -2,7 +2,7 @@
 id: kibi-usage
 name: Kibi Usage
 description: Use Kibi's source-first, exact-Git, migration-aware, proof-aware operations safely across MCP or the trusted local CLI, including partial completion repair.
-version: 2.14.0
+version: 2.15.0
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -409,6 +409,14 @@ Prolog `symbol-coverage` also requires the test to `validates` the requirement
 enough. Do not rely on legacy `// implements REQ-<area>-<behavior>` comments as the
 traceability record.
 
+Set the symbol's `title` to the behavioral member the extractor can locate in
+`sourceFile`: `ClassName.methodName`, an exported function, or a class, not a
+file or module name. A traceability link (`implements`, `covered_by`, …) from
+a symbol whose `title` names no such member is refused by the granularity gate
+when the file already has granular behavioral symbols, unless the symbol sets
+`granularity_reason` to `config-artifact`, `module-level-behavior`,
+`extractor-miss`, `legacy-link` or `test-suite`.
+
 ## Complete Logical Coverage
 
 Decompose all atomic normative clauses into `claim_key`/`claim_text` entries in