kibi-cli 2.18.0 → 2.19.0

package/dist/public/operations/catalog.d.ts

@@ -79,7 +79,7 @@ export declare const OPERATION_CATALOG: readonly [{
 }, {
     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: {
@@ -103,6 +103,55 @@ export declare const OPERATION_CATALOG: readonly [{
                 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;

package/dist/public/operations/catalog.d.ts.map

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

package/dist/public/operations/contracts.js

@@ -345,10 +345,7 @@ const BASE_DATA_SCHEMAS = {
         sourceType: stringValue,
     }),
     kb_skills_read: objectData({ content: stringValue }, ["content"]),
-    kb_query: objectData({ entities: recordArray, count: integerValue }, [
-        "entities",
-        "count",
-    ]),
+    kb_query: objectData({ entities: recordArray, count: integerValue, factQuery: recordValue }, ["entities", "count"]),
     kb_search: objectData({
         results: valueArray,
         count: integerValue,

package/dist/public/operations/discovery-executors.d.ts

@@ -12,11 +12,47 @@ 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 declare const FACT_KINDS: readonly ["subject", "property_value", "predicate", "predicate_schema", "observation", "meta", "rule", "rule_schema"];
 export type SearchInput = {
     readonly query: string;
     readonly type?: string;

package/dist/public/operations/discovery-executors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discovery-executors.d.ts","sourceRoot":"","sources":["../../../src/public/operations/discovery-executors.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EAGpB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EAAE,KAAK,YAAY,EAAqB,MAAM,wBAAwB,CAAC;AAE9E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D,OAAO,EACL,yBAAyB,EACzB,KAAK,qBAAqB,EAM3B,MAAM,6BAA6B,CAAC;AAUrC,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAGnB,MAAM,qBAAqB,CAAC;AAK7B,OAAO,KAAK,EAAE,gBAAgB,EAAc,MAAM,oBAAoB,CAAC;AACvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAGlD,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IACtD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,GAAG,WAAW,CAAC;IAC9C,QAAQ,CAAC,cAAc,CAAC,EAAE,kBAAkB,CAAC;IAC7C,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IACrD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,WAAW,GAAG,iBAAiB,CAAC,EAAE,CAAC;IAC/D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,aAAa,CAAC,EAAE,oBAAoB,CAAC;IAC9C,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;IAC/B,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,CAAC,EAAE,uBAAuB,CAAC;CAChD,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,OAAO,yBAAyB,CAAC;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACzD,CAAC;AA6BF,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;AAE1D,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,sBAAsB,CAAC,EAAE,OAAO,CAAC;IAC1C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAC3D,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,OAAO,CAAC;IACzC,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IACtD,QAAQ,CAAC,gBAAgB,CAAC,EAAE;QAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,IAAI,EACT,OAAO,GACP,mBAAmB,GACnB,eAAe,GACf,mBAAmB,CAAC;QACxB,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;KACrC,CAAC;IACF,QAAQ,CAAC,oBAAoB,CAAC,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IACnE,QAAQ,CAAC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAC3C,QAAQ,CAAC,6BAA6B,CAAC,EAAE,OAAO,CAAC;IACjD,QAAQ,CAAC,WAAW,CAAC,EAAE,qBAAqB,CAAC;IAC7C,QAAQ,CAAC,YAAY,CAAC,EAAE;QACtB,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,aAAa,CAAC;QAC1C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;KACpC,CAAC;IACF,QAAQ,CAAC,YAAY,CAAC,EAAE,qBAAqB,CAAC;IAC9C,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC,QAAQ,CAAC,SAAS,CAAC,EAAE;QACnB,QAAQ,CAAC,sBAAsB,CAAC,EAAE,SAAS,QAAQ,CACjD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CACxB,EAAE,CAAC;QACJ,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;QACjC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;QAChC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;QAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;KACzD,CAAC;CACH,CAAC;AAqBF,wBAAsB,YAAY,CAChC,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC,CA2CxC;AAmDD,wBAAsB,aAAa,CACjC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CA6HzC;AAED,wBAAsB,aAAa,CACjC,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CAmUzC"}
+{"version":3,"file":"discovery-executors.d.ts","sourceRoot":"","sources":["../../../src/public/operations/discovery-executors.ts"],"names":[],"mappings":"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"}

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 = {

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;

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0GuC,CAAC;AAE/D,eAAO,MAAM,UAAU;;;;;;;;;;;;CAWuC,CAAC"}