kibi-cli 2.18.0 → 2.20.0

package/dist/public/operations/discovery-executors.js

@@ -11,8 +11,45 @@ import { BRANCH_STORE_NOT_COMPILED, branchStoreReason, inspectBranchStore, store
 import { confirmSourceNewerReasons } from "../../utils/content-freshness.js";
 import { loadSearchCandidates, paginateResults, queryEntitiesViaQuery, reloadFullEntities, validateEntityType, } from "./discovery-entities.js";
 import { buildActionsFromStatus, readMigrationConfigStatus, } from "./migration-plan.js";
-import { OperationJsonDecodeError, runOperationJsonQuery, } from "./prolog-json.js";
+import { OperationJsonDecodeError, runOperationJsonQuery, toPrologAtom, } from "./prolog-json.js";
 import { readWorkspaceSnapshot } from "./workspace-snapshot.js";
+export const FACT_KINDS = [
+    "subject",
+    "property_value",
+    "predicate",
+    "predicate_schema",
+    "observation",
+    "meta",
+    "rule",
+    "rule_schema",
+];
+/** Which typed filters each question mode reads; any other is refused. */
+const MODE_FILTERS = {
+    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",
+];
 /**
  * An empty result from a store that was never compiled says nothing about
  * the authored requirements, so search reports the store state itself (the
@@ -51,11 +88,334 @@ function isStatusPayload(value) {
         typeof record.dirty === "boolean" &&
         typeof record.syncState === "string");
 }
+function hasTypedFactFilters(input) {
+    return TYPED_FACT_FILTERS.some((key) => input[key] !== undefined);
+}
+function requireAtomString(value, field) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new Error(`${field} must be a non-empty string.`);
+    }
+    return value.trim();
+}
+function requireEnum(value, field, allowed) {
+    if (typeof value !== "string" || !allowed.includes(value)) {
+        throw new Error(`${field} must be one of: ${allowed.join(", ")}.`);
+    }
+    return value;
+}
+/**
+ * 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) {
+    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 "[]";
+}
+function callText(args) {
+    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, response) {
+    const next = [];
+    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?.argumentNames)
+                ? response.schema.argumentNames.filter((name) => 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) {
+    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, context, limit, offset) {
+    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"]) {
+        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;
+    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(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 = {
+        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.argument)}: ${JSON.stringify(factQuery.distinct.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, context) {
     // implements REQ-kibi-operation-interface-parity
     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 = {
@@ -133,7 +493,7 @@ async function projectMatches(prolog, matches, fields) {
 }
 export async function executeSearch(input, context) {
     // implements REQ-kibi-operation-interface-parity, REQ-mcp-search-discovery
-    const { query, type, limit = 20, offset = 0, rankingMode = "intent-v1", semanticFacets, sourceLocations, minScore, fields = "summary", answer, } = input;
+    const { query, type, limit = 10, offset = 0, rankingMode = "intent-v1", semanticFacets, sourceLocations, minScore, fields = "summary", answer, } = input;
     const trimmedQuery = query.trim();
     if (!trimmedQuery) {
         throw new Error("Search execution failed: query must be a non-empty string");
@@ -174,17 +534,21 @@ export async function executeSearch(input, context) {
                 : undefined;
             // The structured payload carries every row; the text is a short
             // human-readable digest instead of a second copy of the results.
+            // A top match no requirement owns is said in the digest too, so the
+            // governing list is never read as the top match's requirement.
+            const topUngoverned = answerLayer?.ungoverned.find((entry) => entry.rank === 1);
             const text = `${intentResult.matches.length === 0
                 ? `No intent search results for '${trimmedQuery}' (abstained).`
                 : `Found ${intentResult.matches.length} intent search results for '${trimmedQuery}'${intentResult.analysis.ambiguous ? " (top matches are close; confirm before relying on one)" : ""}. Top: ${paginated
                     .slice(0, 5)
                     .map((match) => String(match.entity.id ?? ""))
-                    .join(", ")}${answerLayer ? `. Governing: ${answerLayer.governing.map((req) => req.id).join(", ") || "none found"}` : ""}.`}${storeNote}`;
+                    .join(", ")}${answerLayer ? `. Governing: ${answerLayer.governing.map((req) => req.id).join(", ") || "none found"}` : ""}${topUngoverned ? ` (the top match ${topUngoverned.id} is linked to no requirement)` : ""}.`}${storeNote}`;
             return {
                 content: [{ type: "text", text }],
                 structuredContent: {
                     results: await projectMatches(prolog, paginated, fields),
                     count: intentResult.matches.length,
+                    returned: paginated.length,
                     truncated: offset + paginated.length < intentResult.matches.length,
                     queryAnalysis: intentResult.analysis,
                     ...(answerLayer ? { answer: answerLayer } : {}),
@@ -211,6 +575,7 @@ export async function executeSearch(input, context) {
             structuredContent: {
                 results: await projectMatches(prolog, paginated, fields),
                 count: matches.length,
+                returned: paginated.length,
                 truncated: offset + paginated.length < matches.length,
                 ...branchFields,
             },

package/dist/public/operations/specs/composite.d.ts

@@ -344,7 +344,7 @@ export declare const skillsSpec: {
 export declare const modelSpec: {
     readonly name: "kb_model";
     readonly cliName: "model";
-    readonly description: "Turn requirement prose into checkable structure without writing the KB. mode:analyze returns the semantic advisor receipt: the clause ledger, what is grounded, what is ambiguous and suggested modeling (pass clauses for compound prose and optional typed kibi.logic.v1 interpretations). mode:requirement converts one claim (subjectKey, propertyKey, operator, value, or typed logic) into a strict-lane write set and applyPlan. mode:predicates ranks ontology predicate schemas and returns an applicable predicate-fact plan only for reviewed bindings, otherwise an ontology-gap observation. Apply returned plans with kb_upsert.";
+    readonly description: "Turn requirement prose into checkable structure without writing the KB. mode:analyze returns the semantic advisor receipt: the clause ledger, what is grounded, what is ambiguous and suggested modeling (pass clauses for compound prose and optional typed kibi.logic.v1 interpretations). mode:requirement converts one claim (subjectKey, propertyKey, operator, value, or typed logic) into a strict-lane write set and applyPlan. mode:predicates ranks ontology predicate schemas and returns an applicable predicate-fact plan only for reviewed bindings, otherwise an ontology-gap observation. With requirementId, mode:predicates also returns a hash-bound plan (fact write plus requires_predicate link) for kb_apply_plan, whose contradictionAnalysis is the what-if over the current KB; other returned plans apply with kb_upsert, and kb_upsert dryRun with plannedFacts previews a requirement before its facts exist.";
     readonly businessInputSchema: {
         readonly type: "object";
         readonly required: readonly ["mode", "text"];

package/dist/public/operations/specs/composite.js

@@ -152,7 +152,7 @@ export const skillsSpec = {
 export const modelSpec = {
     name: "kb_model",
     cliName: "model",
-    description: "Turn requirement prose into checkable structure without writing the KB. mode:analyze returns the semantic advisor receipt: the clause ledger, what is grounded, what is ambiguous and suggested modeling (pass clauses for compound prose and optional typed kibi.logic.v1 interpretations). mode:requirement converts one claim (subjectKey, propertyKey, operator, value, or typed logic) into a strict-lane write set and applyPlan. mode:predicates ranks ontology predicate schemas and returns an applicable predicate-fact plan only for reviewed bindings, otherwise an ontology-gap observation. Apply returned plans with kb_upsert.",
+    description: "Turn requirement prose into checkable structure without writing the KB. mode:analyze returns the semantic advisor receipt: the clause ledger, what is grounded, what is ambiguous and suggested modeling (pass clauses for compound prose and optional typed kibi.logic.v1 interpretations). mode:requirement converts one claim (subjectKey, propertyKey, operator, value, or typed logic) into a strict-lane write set and applyPlan. mode:predicates ranks ontology predicate schemas and returns an applicable predicate-fact plan only for reviewed bindings, otherwise an ontology-gap observation. With requirementId, mode:predicates also returns a hash-bound plan (fact write plus requires_predicate link) for kb_apply_plan, whose contradictionAnalysis is the what-if over the current KB; other returned plans apply with kb_upsert, and kb_upsert dryRun with plannedFacts previews a requirement before its facts exist.",
     businessInputSchema: {
         type: "object",
         required: ["mode", "text"],

package/dist/public/operations/specs/discovery.d.ts

@@ -2,7 +2,7 @@ import { executeQuery, executeSearch, executeStatus } from "../discovery-executo
 export declare const querySpec: {
     readonly name: "kb_query";
     readonly cliName: "query";
-    readonly 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.";
+    readonly description: "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.";
     readonly businessInputSchema: {
         readonly type: "object";
         readonly properties: {
@@ -26,6 +26,55 @@ export declare const querySpec: {
                 readonly type: "string";
                 readonly description: "Optional source-file substring filter. Example: 'src/auth/login.ts'. Uses KB source linkage, not file-system scanning.";
             };
+            readonly factKind: {
+                readonly type: "string";
+                readonly enum: readonly ["subject", "property_value", "predicate", "predicate_schema", "observation", "meta", "rule", "rule_schema"];
+                readonly 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'.";
+            };
+            readonly predicate: {
+                readonly type: "string";
+                readonly 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.";
+            };
+            readonly namespace: {
+                readonly type: "string";
+                readonly description: "Optional predicate namespace when the same name exists in several. Default: any namespace.";
+            };
+            readonly where: {
+                readonly type: "object";
+                readonly additionalProperties: {
+                    readonly type: "string";
+                };
+                readonly 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.";
+            };
+            readonly args: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: readonly ["string", "null"];
+                };
+                readonly description: "Positional argument values for predicate when it has no schema; null matches any value. Example: ['admin', null, null, 'allow']. Prefer where.";
+            };
+            readonly polarity: {
+                readonly type: "string";
+                readonly enum: readonly ["assert", "deny"];
+                readonly description: "Optional polarity filter for predicate facts. Default: both.";
+            };
+            readonly scope: {
+                readonly type: "string";
+                readonly enum: readonly ["all", "current_requirements"];
+                readonly description: "Optional: 'current_requirements' keeps only facts a current (not superseded or retired) requirement requires.";
+            };
+            readonly distinct: {
+                readonly type: "string";
+                readonly 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.";
+            };
+            readonly subjectKey: {
+                readonly type: "string";
+                readonly description: "Typed fact filter: dotted subject key whose property facts to list, e.g. 'user.role_assignment'. Combine with propertyKey for one property.";
+            };
+            readonly propertyKey: {
+                readonly type: "string";
+                readonly description: "Optional property key under subjectKey, e.g. 'max_roles'. Returns operator, value and unit of each fact.";
+            };
             readonly limit: {
                 readonly type: "number";
                 readonly default: 100;
@@ -65,8 +114,8 @@ export declare const searchSpec: {
             readonly limit: {
                 readonly type: "integer";
                 readonly minimum: 0;
-                readonly default: 20;
-                readonly description: "Optional max rows to return after ranking. Default: 20.";
+                readonly default: 10;
+                readonly description: "Optional max rows to return after ranking. Default: 10; raise it or page with offset when the answer layer is not enough.";
             };
             readonly offset: {
                 readonly type: "integer";

package/dist/public/operations/specs/discovery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../../../src/public/operations/specs/discovery.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,aAAa,EACb,aAAa,EACd,MAAM,2BAA2B,CAAC;AAsBnC,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgDsC,CAAC;AAE7D,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0GuC,CAAC;AAE/D,eAAO,MAAM,UAAU;;;;;;;;;;;;CAWuC,CAAC"}
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../../../src/public/operations/specs/discovery.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,aAAa,EACb,aAAa,EACd,MAAM,2BAA2B,CAAC;AAiCnC,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuGsC,CAAC;AAE7D,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2GuC,CAAC;AAE/D,eAAO,MAAM,UAAU;;;;;;;;;;;;CAWuC,CAAC"}

package/dist/public/operations/specs/discovery.js

@@ -9,10 +9,20 @@ const ENTITY_TYPES = [
     "symbol",
     "fact",
 ];
+const FACT_KINDS = [
+    "subject",
+    "property_value",
+    "predicate",
+    "predicate_schema",
+    "observation",
+    "meta",
+    "rule",
+    "rule_schema",
+];
 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.",
+    description: "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: {
@@ -34,6 +44,51 @@ export const querySpec = {
                 type: "string",
                 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,
@@ -73,8 +128,8 @@ export const searchSpec = {
             limit: {
                 type: "integer",
                 minimum: 0,
-                default: 20,
-                description: "Optional max rows to return after ranking. Default: 20.",
+                default: 10,
+                description: "Optional max rows to return after ranking. Default: 10; raise it or page with offset when the answer layer is not enough.",
             },
             offset: {
                 type: "integer",