kibi-cli 2.18.0 → 2.20.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;
@@ -76,7 +151,10 @@ export type SearchInput = {
 
 export type SearchPayload = {
   readonly results: readonly (SearchMatch | IntentSearchMatch)[];
+  /** Matches in the whole ranking, before `limit` and `offset`. */
   readonly count: number;
+  /** Rows in `results`: the page this call returned. */
+  readonly returned: number;
   readonly truncated?: boolean;
   readonly queryAnalysis?: IntentSearchAnalysis;
   readonly answer?: SearchAnswer;
@@ -195,6 +273,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 +675,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 = {
@@ -300,7 +775,7 @@ export async function executeSearch(
   const {
     query,
     type,
-    limit = 20,
+    limit = 10,
     offset = 0,
     rankingMode = "intent-v1",
     semanticFacets,
@@ -357,6 +832,11 @@ export async function executeSearch(
           : 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).`
@@ -365,13 +845,14 @@ export async function executeSearch(
               .map((match) => String(match.entity.id ?? ""))
               .join(
                 ", ",
-              )}${answerLayer ? `. Governing: ${answerLayer.governing.map((req) => req.id).join(", ") || "none found"}` : ""}.`
+              )}${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 } : {}),
@@ -411,6 +892,7 @@ export async function executeSearch(
       structuredContent: {
         results: await projectMatches(prolog, paginated, fields),
         count: matches.length,
+        returned: paginated.length,
         truncated: offset + paginated.length < matches.length,
         ...branchFields,
       },

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

@@ -217,7 +217,7 @@ 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.",
+    "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/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,
@@ -99,8 +165,9 @@ 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",

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

@@ -38,6 +38,21 @@ export const upsertSpec = {
         description:
           "Validate the payload and return schema/modeling errors, a normalized preview and the semantic advisor receipt without writing the KB or workspace. Use it as the preflight before the real write.",
       },
+      plannedFacts: {
+        type: "array",
+        description:
+          "dryRun only. Fact upsert payloads (type, id, properties, optional relationships) that will be written before this payload, typically the applyPlan entries kb_model returned. They are validated in order and staged with the payload, so a requires_predicate or requires_property target that does not exist yet resolves, its claim_key is read from the plan, and the contradiction preview runs against the KB as it would be after the whole batch (result: stagedFacts, whatIf). A conflict the batch would introduce, such as an allow and a deny permission_rule on the same key, is refused as the commit would refuse it. Rejected without dryRun: write the facts first.",
+        items: {
+          type: "object",
+          required: ["type", "id", "properties"],
+          properties: {
+            type: { type: "string", const: "fact" },
+            id: { type: "string", minLength: 1 },
+            properties: { type: "object" },
+            relationships: RELATIONSHIPS_SCHEMA,
+          },
+        },
+      },
       document: {
         type: "object",
         additionalProperties: false,