kibi-cli 2.0.0 → 2.2.0

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

@@ -1,4 +1,4 @@
-import type { PrologPort } from "./runtime-types.js";
+import type { PrologEntityQueryInput, PrologEntityQueryResult, PrologPort } from "./runtime-types.js";
 export type EntityQueryInput = {
     readonly type?: string;
     readonly id?: string;
@@ -7,11 +7,63 @@ export type EntityQueryInput = {
     /** Page size for index-backed queries; bounds each query's output. */
     readonly limit?: number;
     readonly offset?: number;
+    /**
+     * Proof selection only needs the contract. Omit receipt histories so a
+     * campaign does not page every full test entity.
+     */
+    readonly projection?: "proof_contract";
 };
 export declare const VALID_ENTITY_TYPES: readonly ["req", "scenario", "test", "adr", "flag", "event", "symbol", "fact"];
 export declare function validateEntityType(type?: string): void;
+/**
+ * Proof campaign selection must not materialize every contracted test in a
+ * single Prolog result. The specialized projection excludes receipt histories
+ * and returns one bounded page at a time.
+ */
+export declare const PROOF_CONTRACT_PAGE_SIZE = 100;
 export declare function buildEntityGoal(input: EntityQueryInput): string;
+export declare function loadEntitiesPaged(prolog: Pick<PrologPort, "query">, type: (typeof VALID_ENTITY_TYPES)[number], pageSize?: number): Promise<Record<string, unknown>[]>;
 export declare function loadEntities(prolog: Pick<PrologPort, "query">, input: EntityQueryInput): Promise<Record<string, unknown>[]>;
 export declare function paginateResults<T>(results: readonly T[], limit?: number, offset?: number): T[];
+/**
+ * Page size for index-backed search candidate fetches. Each page is one
+ * Prolog query, so a fixed page size substantially bounds each response and
+ * fixes the observed large-KB output overflow; it is a practical bound, not
+ * a byte-size guarantee for arbitrarily large individual entity payloads.
+ */
+export declare const SEARCH_CANDIDATE_PAGE_SIZE = 500;
+export declare function loadSearchCandidates(prolog: Pick<PrologPort, "searchEntities"> & Partial<Pick<PrologPort, "query">>, input: {
+    readonly query: string;
+    readonly type?: string;
+    readonly maxCandidates?: number;
+}, signal?: AbortSignal): Promise<Record<string, unknown>[]>;
+/**
+ * Projected candidate rows for every entity (optionally of one type), in id
+ * order, bounded by `maxCandidates`. For semantic discovery that has no
+ * lexical token to pre-filter candidates.
+ */
+export declare function listSearchCandidates(prolog: Pick<PrologPort, "query">, input: {
+    readonly type?: string;
+    readonly maxCandidates: number;
+}, signal?: AbortSignal): Promise<Record<string, unknown>[]>;
+/**
+ * Rows per `kb_query_entities` request. Full entities carry receipt
+ * histories, so a caller-sized page (up to 100k rows) is split into bounded
+ * requests and concatenated; the reported count is the total match count.
+ */
+export declare const ENTITY_QUERY_CHUNK_SIZE = 25;
+export declare function queryEntityChunks(readChunk: (input: PrologEntityQueryInput) => Promise<PrologEntityQueryResult>, input: PrologEntityQueryInput): Promise<PrologEntityQueryResult>;
+/** Bounded `kb_query_entities` paging for ports without the engine method. */
+export declare function queryEntitiesViaQuery(prolog: Pick<PrologPort, "query">, input: PrologEntityQueryInput, signal?: AbortSignal): Promise<PrologEntityQueryResult>;
+/** Every entity id, without materializing entity properties. */
+export declare function loadEntityIds(prolog: Pick<PrologPort, "query">): Promise<string[]>;
+/**
+ * Replace projected search candidates with complete entities, one bounded
+ * query per entity. Used only for the final result page when a caller asks
+ * for full entity bodies.
+ */
+export declare function reloadFullEntities<TMatch extends {
+    readonly entity: Record<string, unknown>;
+}>(prolog: Pick<PrologPort, "query">, matches: readonly TMatch[]): Promise<TMatch[]>;
 export declare function dedupeEntities(entities: readonly Record<string, unknown>[]): Record<string, unknown>[];
 //# sourceMappingURL=discovery-entities.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"discovery-entities.d.ts","sourceRoot":"","sources":["../../../src/public/operations/discovery-entities.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,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,sEAAsE;IACtE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,eAAO,MAAM,kBAAkB,gFASrB,CAAC;AAGX,wBAAgB,kBAAkB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAMtD;AAGD,wBAAgB,eAAe,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAoC/D;AAGD,wBAAsB,YAAY,CAChC,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,EACjC,KAAK,EAAE,gBAAgB,GACtB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CA0BpC;AAGD,wBAAgB,eAAe,CAAC,CAAC,EAC/B,OAAO,EAAE,SAAS,CAAC,EAAE,EACrB,KAAK,SAAM,EACX,MAAM,SAAI,GACT,CAAC,EAAE,CAEL;AAGD,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAC3C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAQ3B"}
+{"version":3,"file":"discovery-entities.d.ts","sourceRoot":"","sources":["../../../src/public/operations/discovery-entities.ts"],"names":[],"mappings":"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"}

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

@@ -1,4 +1,4 @@
-import { escapeAtomContent, parseEntityFromBinding, parseEntityFromList, parseListOfLists, } from "../../prolog/codec.js";
+import { escapeAtomContent, normalizeEntityId, parseAtomList, parseEntityFromBinding, parseEntityFromList, parseListOfLists, } from "../../prolog/codec.js";
 export const VALID_ENTITY_TYPES = [
     "req",
     "scenario",
@@ -15,9 +15,21 @@ export function validateEntityType(type) {
         throw new Error(`Invalid type '${type}'. Valid types: ${VALID_ENTITY_TYPES.join(", ")}. Use a single type value, or omit this parameter to query all entities.`);
     }
 }
+/**
+ * Proof campaign selection must not materialize every contracted test in a
+ * single Prolog result. The specialized projection excludes receipt histories
+ * and returns one bounded page at a time.
+ */
+export const PROOF_CONTRACT_PAGE_SIZE = 100;
 // implements REQ-002, REQ-013
 export function buildEntityGoal(input) {
     const { type, id, tags, sourceFile } = input;
+    if (type === "test" && input.projection === "proof_contract") {
+        const idTerm = id ? `some('${escapeAtomContent(id)}')` : "none";
+        const limit = input.limit ?? PROOF_CONTRACT_PAGE_SIZE;
+        const offset = input.offset ?? 0;
+        return `kb_query_proof_contracts(${idTerm},${limit},${offset},Results)`;
+    }
     if (sourceFile) {
         const safeSource = escapeAtomContent(sourceFile);
         if (type) {
@@ -53,21 +65,61 @@ export function buildEntityGoal(input) {
     }
     return "findall([Id,Type,Props], kb_entity(Id, Type, Props), Results)";
 }
+/**
+ * Full test entities carry their receipt histories, which only grow. Callers
+ * that must see every full entity of a type page through the indexed query so
+ * no single Prolog answer can approach the bounded output capacity.
+ */
+const FULL_ENTITY_PAGE_SIZE = 25;
+// implements REQ-002, REQ-013
+export async function loadEntitiesPaged(prolog, type, pageSize = FULL_ENTITY_PAGE_SIZE) {
+    if (!Number.isInteger(pageSize) || pageSize <= 0) {
+        throw new Error("loadEntitiesPaged pageSize must be a positive integer");
+    }
+    const entities = [];
+    for (let offset = 0;; offset += pageSize) {
+        const page = await loadEntities(prolog, { type, limit: pageSize, offset });
+        entities.push(...page);
+        if (page.length < pageSize)
+            break;
+    }
+    return dedupeEntities(entities);
+}
 // implements REQ-002, REQ-013
 export async function loadEntities(prolog, input) {
     validateEntityType(input.type);
-    const queryResult = await prolog.query(buildEntityGoal(input));
-    if (!queryResult.success) {
-        throw new Error(queryResult.error || "Query failed with unknown error");
-    }
-    let entities = [];
-    const resultsBinding = queryResult.bindings.Results;
-    const resultBinding = queryResult.bindings.Result;
-    if (resultsBinding) {
-        entities = parseListOfLists(resultsBinding).map(parseEntityFromList);
+    const readPage = async (pageInput) => {
+        const queryResult = await prolog.query(buildEntityGoal(pageInput));
+        if (!queryResult.success) {
+            throw new Error(queryResult.error || "Query failed with unknown error");
+        }
+        const resultsBinding = queryResult.bindings.Results;
+        const resultBinding = queryResult.bindings.Result;
+        if (resultsBinding) {
+            return parseListOfLists(resultsBinding).map(parseEntityFromList);
+        }
+        return resultBinding ? [parseEntityFromBinding(resultBinding)] : [];
+    };
+    let entities;
+    if (input.type === "test" &&
+        input.projection === "proof_contract" &&
+        input.id === undefined &&
+        input.limit === undefined &&
+        input.offset === undefined) {
+        entities = [];
+        for (let offset = 0;; offset += PROOF_CONTRACT_PAGE_SIZE) {
+            const page = await readPage({
+                ...input,
+                limit: PROOF_CONTRACT_PAGE_SIZE,
+                offset,
+            });
+            entities.push(...page);
+            if (page.length < PROOF_CONTRACT_PAGE_SIZE)
+                break;
+        }
     }
-    else if (resultBinding) {
-        entities = [parseEntityFromBinding(resultBinding)];
+    else {
+        entities = await readPage(input);
     }
     if (input.tags && input.tags.length > 0) {
         const requested = new Set(input.tags.map((tag) => tag.trim()));
@@ -83,6 +135,161 @@ export async function loadEntities(prolog, input) {
 export function paginateResults(results, limit = 100, offset = 0) {
     return results.slice(offset, offset + limit);
 }
+/**
+ * Page size for index-backed search candidate fetches. Each page is one
+ * Prolog query, so a fixed page size substantially bounds each response and
+ * fixes the observed large-KB output overflow; it is a practical bound, not
+ * a byte-size guarantee for arbitrarily large individual entity payloads.
+ */
+// implements REQ-kibi-operation-interface-parity, REQ-mcp-search-discovery
+export const SEARCH_CANDIDATE_PAGE_SIZE = 500;
+function isPrologOutputOverflow(error) {
+    return error instanceof Error && error.message.includes("ENOBUFS");
+}
+// implements REQ-kibi-operation-interface-parity, REQ-mcp-search-discovery
+export async function loadSearchCandidates(prolog, input, signal) {
+    // Call through the port property, never via a detached local: EngineClient
+    // searchEntities depends on `this` (this.command), and the PrologPort
+    // contract does not promise a pre-bound method. Ports without the indexed
+    // engine method run the same bounded Prolog search through `query`.
+    const readPage = (page) => {
+        if (prolog.searchEntities)
+            return prolog.searchEntities(page, signal);
+        const query = prolog.query;
+        if (query === undefined)
+            return Promise.resolve({ entities: [], count: 0 });
+        return searchEntitiesViaQuery({ query: (goal, querySignal) => query.call(prolog, goal, querySignal) }, page, signal);
+    };
+    return readCandidatePages(readPage, input);
+}
+/**
+ * Projected candidate rows for every entity (optionally of one type), in id
+ * order, bounded by `maxCandidates`. For semantic discovery that has no
+ * lexical token to pre-filter candidates.
+ */
+// implements REQ-kibi-operation-interface-parity, REQ-mcp-search-discovery
+export async function listSearchCandidates(prolog, input, signal) {
+    const type = input.type ? `'${escapeAtomContent(input.type)}'` : "none";
+    return readCandidatePages((page) => readRowsAndCount(prolog, `kb_list_search_candidates(${type}, ${page.limit}, ${page.offset}, Rows, Count)`, "Search candidate listing failed", signal), { query: "", maxCandidates: input.maxCandidates });
+}
+async function readCandidatePages(readPage, input) {
+    const maxCandidates = input.maxCandidates ?? Number.POSITIVE_INFINITY;
+    const candidates = [];
+    let offset = 0;
+    let total = Number.POSITIVE_INFINITY;
+    let pageSize = SEARCH_CANDIDATE_PAGE_SIZE;
+    while (offset < total && candidates.length < maxCandidates) {
+        let page;
+        try {
+            page = await readPage({
+                query: input.query,
+                ...(input.type !== undefined ? { type: input.type } : {}),
+                limit: pageSize,
+                offset,
+            });
+        }
+        catch (error) {
+            // A page of unusually large rows can still exceed the bounded Prolog
+            // output. Halve the page and retry the same offset; the smaller size is
+            // kept for the rest of the scan. Only a single row that overflows on its
+            // own is a real failure.
+            if (pageSize > 1 && isPrologOutputOverflow(error)) {
+                pageSize = Math.max(1, Math.floor(pageSize / 2));
+                continue;
+            }
+            throw error;
+        }
+        if (page.entities.length === 0)
+            break;
+        candidates.push(...page.entities);
+        total = page.count;
+        offset += page.entities.length;
+    }
+    return Number.isFinite(maxCandidates)
+        ? candidates.slice(0, maxCandidates)
+        : candidates;
+}
+function searchEntitiesViaQuery(prolog, input, signal) {
+    const type = input.type ? `'${escapeAtomContent(input.type)}'` : "none";
+    return readRowsAndCount(prolog, `kb_search_entities(${type}, '${escapeAtomContent(input.query)}', ${input.limit}, ${input.offset}, Rows, Count)`, "Indexed search candidate query failed", signal);
+}
+async function readRowsAndCount(prolog, goal, errorLabel, signal) {
+    const result = await prolog.query(goal, signal);
+    if (!result.success) {
+        // Same message as the engine client's indexed methods, so both surfaces
+        // report a failure identically.
+        throw new Error(result.error ?? errorLabel);
+    }
+    const entities = result.bindings.Rows
+        ? parseListOfLists(result.bindings.Rows).map(parseEntityFromList)
+        : [];
+    const count = Number.parseInt(result.bindings.Count ?? "0", 10);
+    return { entities, count: Number.isFinite(count) ? count : entities.length };
+}
+/**
+ * Rows per `kb_query_entities` request. Full entities carry receipt
+ * histories, so a caller-sized page (up to 100k rows) is split into bounded
+ * requests and concatenated; the reported count is the total match count.
+ */
+export const ENTITY_QUERY_CHUNK_SIZE = 25;
+// implements REQ-kibi-operation-interface-parity
+export async function queryEntityChunks(readChunk, input) {
+    const entities = [];
+    let count = 0;
+    let first = true;
+    while (first || entities.length < input.limit) {
+        const chunkLimit = Math.min(ENTITY_QUERY_CHUNK_SIZE, input.limit - entities.length);
+        const chunk = await readChunk({
+            ...input,
+            limit: chunkLimit,
+            offset: input.offset + entities.length,
+        });
+        if (first)
+            count = chunk.count;
+        first = false;
+        entities.push(...chunk.entities);
+        if (chunk.entities.length < chunkLimit || chunkLimit === 0)
+            break;
+    }
+    return { entities, count };
+}
+/** Bounded `kb_query_entities` paging for ports without the engine method. */
+// implements REQ-kibi-operation-interface-parity
+export function queryEntitiesViaQuery(prolog, input, signal) {
+    const atom = (value) => value === undefined ? "none" : `'${escapeAtomContent(value)}'`;
+    const tags = `[${(input.tags ?? []).map((tag) => `'${escapeAtomContent(tag)}'`).join(",")}]`;
+    return queryEntityChunks((chunk) => readRowsAndCount(prolog, `kb_query_entities(${atom(chunk.type)}, ${atom(chunk.id)}, ${tags}, ${atom(chunk.sourceFile)}, ${chunk.limit}, ${chunk.offset}, Rows, Count)`, "Indexed entity query failed", signal), input);
+}
+/** Every entity id, without materializing entity properties. */
+// implements REQ-002
+export async function loadEntityIds(prolog) {
+    const result = await prolog.query("kb_entity_ids(Ids)");
+    if (!result.success) {
+        throw new Error(`Entity id enumeration failed: ${result.error ?? "Unknown error"}`);
+    }
+    return parseAtomList(result.bindings.Ids ?? "[]").map(normalizeEntityId);
+}
+/**
+ * Replace projected search candidates with complete entities, one bounded
+ * query per entity. Used only for the final result page when a caller asks
+ * for full entity bodies.
+ */
+// implements REQ-mcp-search-discovery
+export async function reloadFullEntities(prolog, matches) {
+    const reloaded = [];
+    for (const match of matches) {
+        const id = String(match.entity.id ?? "");
+        const type = match.entity.type;
+        const [full] = id
+            ? await loadEntities(prolog, {
+                id,
+                ...(typeof type === "string" ? { type } : {}),
+            })
+            : [];
+        reloaded.push(full ? { ...match, entity: full } : match);
+    }
+    return reloaded;
+}
 // implements REQ-002
 export function dedupeEntities(entities) {
     const seen = new Set();

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

@@ -25,6 +25,7 @@ export type SearchInput = {
     readonly semanticFacets?: IntentSearchFacets;
     readonly sourceLocations?: readonly SourceLocation[];
     readonly minScore?: number;
+    readonly fields?: "summary" | "full";
 };
 export type SearchPayload = {
     readonly results: readonly (SearchMatch | IntentSearchMatch)[];

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":"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"}
+{"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

@@ -1,10 +1,11 @@
+import { compilerFingerprintReason } from "../../commands/sync/cache.js";
 import { EngineClient } from "../../engine.js";
 import { executeIntentSearch, validateIntentSearchInput, } from "../../intent-search.js";
 import { classifyActivation } from "../../operations/bootstrap/activation.js";
 import { rankEntities } from "../../search-ranking.js";
 import { resolveBranchAttachment } from "../../utils/branch-resolver.js";
-import { branchStoreReason, storeLockJournalReason, inspectBranchStore, } from "../../utils/branch-store.js";
-import { loadEntities, paginateResults, validateEntityType, } from "./discovery-entities.js";
+import { branchStoreReason, inspectBranchStore, storeLockJournalReason, } from "../../utils/branch-store.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 { readWorkspaceSnapshot } from "./workspace-snapshot.js";
@@ -28,42 +29,28 @@ 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);
         const prolog = requireProlog(context);
-        const indexedPage = prolog.queryEntities
-            ? await prolog.queryEntities({
-                ...(type !== undefined ? { type } : {}),
-                ...(id !== undefined ? { id } : {}),
-                ...(tags !== undefined ? { tags } : {}),
-                ...(sourceFile !== undefined ? { sourceFile } : {}),
-                limit,
-                offset,
-            })
-            : null;
-        if (indexedPage !== null) {
-            const paginated = indexedPage.entities;
-            const text = indexedPage.count === 0
-                ? `No entities found${type ? ` of type '${type}'` : ""}.`
-                : `Found ${indexedPage.count} entities${type ? ` of type '${type}'` : ""}. Showing ${paginated.length} (offset ${offset}, limit ${limit}): ${paginated
-                    .map((entity) => {
-                    const entityId = String(entity.id ?? "").replace(/^file:\/\/.*\//, "");
-                    return `${entityId} (${String(entity.title ?? "")}, status=${String(entity.status ?? "")})`;
-                })
-                    .join(", ")}`;
-            return {
-                content: [{ type: "text", text }],
-                structuredContent: { entities: paginated, count: indexedPage.count },
-            };
-        }
-        const entities = await loadEntities(requireProlog(context), {
+        const signal = context.signal;
+        const pageInput = {
             ...(type !== undefined ? { type } : {}),
             ...(id !== undefined ? { id } : {}),
             ...(tags !== undefined ? { tags } : {}),
             ...(sourceFile !== undefined ? { sourceFile } : {}),
-        });
-        const paginated = paginateResults(entities, limit, offset);
-        const text = entities.length === 0
+            limit,
+            offset,
+        };
+        // Both paths return one bounded page plus the total count. Ports without
+        // the engine method page kb_query_entities through `query` instead of
+        // materializing every matching entity (receipt histories make an
+        // all-tests answer exceed the bounded engine output).
+        const indexedPage = prolog.queryEntities
+            ? await prolog.queryEntities(pageInput, signal)
+            : await queryEntitiesViaQuery(prolog, pageInput, signal);
+        const paginated = indexedPage.entities;
+        const text = indexedPage.count === 0
             ? `No entities found${type ? ` of type '${type}'` : ""}.`
-            : `Found ${entities.length} entities${type ? ` of type '${type}'` : ""}. Showing ${paginated.length} (offset ${offset}, limit ${limit}): ${paginated
+            : `Found ${indexedPage.count} entities${type ? ` of type '${type}'` : ""}. Showing ${paginated.length} (offset ${offset}, limit ${limit}): ${paginated
                 .map((entity) => {
                 const entityId = String(entity.id ?? "").replace(/^file:\/\/.*\//, "");
                 return `${entityId} (${String(entity.title ?? "")}, status=${String(entity.status ?? "")})`;
@@ -71,7 +58,7 @@ export async function executeQuery(input, context) {
                 .join(", ")}`;
         return {
             content: [{ type: "text", text }],
-            structuredContent: { entities: paginated, count: entities.length },
+            structuredContent: { entities: paginated, count: indexedPage.count },
         };
     }
     catch (error) {
@@ -79,9 +66,48 @@ export async function executeQuery(input, context) {
         throw new Error(`Query execution failed: ${message}`);
     }
 }
+/**
+ * Identifying metadata a caller needs to decide which hits to open.
+ *
+ * Search is a discovery step, so returning complete entity bodies for every
+ * hit spends a large share of an agent's context before it has chosen
+ * anything. Full bodies stay available through `fields: "full"` or a follow-up
+ * kb_query for the exact ids.
+ */
+const SUMMARY_ENTITY_FIELDS = [
+    "id",
+    "type",
+    "title",
+    "status",
+    "priority",
+    "tags",
+    "source",
+    "sourceFile",
+    "updated_at",
+];
+function summarizeMatch(match) {
+    const entity = match.entity;
+    if (entity === null || typeof entity !== "object" || Array.isArray(entity)) {
+        return match;
+    }
+    const row = entity;
+    const summary = {};
+    for (const field of SUMMARY_ENTITY_FIELDS) {
+        if (row[field] !== undefined)
+            summary[field] = row[field];
+    }
+    return { ...match, entity: summary };
+}
+// Candidates are projected rows, so `fields: "full"` reloads the final page's
+// complete entities by id (one bounded query each).
+async function projectMatches(prolog, matches, fields) {
+    return fields === "full"
+        ? reloadFullEntities(prolog, matches)
+        : matches.map(summarizeMatch);
+}
 export async function executeSearch(input, context) {
     // implements REQ-kibi-operation-interface-parity, REQ-mcp-search-discovery
-    const { query, type, limit = 20, offset = 0, rankingMode = "legacy", semanticFacets, sourceLocations, minScore, } = input;
+    const { query, type, limit = 20, offset = 0, rankingMode = "legacy", semanticFacets, sourceLocations, minScore, fields = "summary", } = input;
     const trimmedQuery = query.trim();
     if (!trimmedQuery) {
         throw new Error("Search execution failed: query must be a non-empty string");
@@ -111,25 +137,19 @@ export async function executeSearch(input, context) {
             return {
                 content: [{ type: "text", text }],
                 structuredContent: {
-                    results: paginated,
+                    results: await projectMatches(prolog, paginated, fields),
                     count: intentResult.matches.length,
                     queryAnalysis: intentResult.analysis,
                 },
             };
         }
-        const indexedCandidates = prolog.searchEntities
-            ? await prolog.searchEntities({
-                query: trimmedQuery,
-                ...(type !== undefined ? { type } : {}),
-                limit: 100_000,
-                offset: 0,
-            })
-            : null;
-        const entities = indexedCandidates
-            ? [...indexedCandidates.entities]
-            : await loadEntities(prolog, {
-                ...(type !== undefined ? { type } : {}),
-            });
+        // Candidates are projected rows (no receipt histories or other large
+        // structured properties); ports without the engine method run the same
+        // bounded Prolog search through `query`.
+        const entities = await loadSearchCandidates(prolog, {
+            query: trimmedQuery,
+            ...(type !== undefined ? { type } : {}),
+        }, context.signal);
         const matches = await rankEntities(entities, trimmedQuery, context.workspaceRoot);
         const paginated = paginateResults(matches, limit, offset);
         const text = matches.length === 0
@@ -139,7 +159,10 @@ export async function executeSearch(input, context) {
                 .join(", ")}`;
         return {
             content: [{ type: "text", text }],
-            structuredContent: { results: paginated, count: matches.length },
+            structuredContent: {
+                results: await projectMatches(prolog, paginated, fields),
+                count: matches.length,
+            },
         };
     }
     catch (error) {
@@ -180,16 +203,22 @@ export async function executeStatus(_input, context) {
         }
         else
             try {
-                const prolog = context.prolog ??
-                    (() => {
-                        ownedEngine = new EngineClient({
-                            workspaceRoot: context.workspaceRoot,
-                            branch: attachment.kbBranch,
-                            timeout: 15_000,
-                        });
-                        return ownedEngine;
-                    })();
-                payload = await runOperationJsonQuery(prolog, "status.pl", "status:kb_status_json(JsonString)", "Status execution");
+                // Prefer an injected or session-backed engine so MCP status shares the
+                // same client as discovery tools. Only spawn an owned fallback when no
+                // host session is available (CLI status without a live runtime port).
+                let prolog = context.prolog;
+                if (!prolog && context.ensureProlog) {
+                    prolog = await context.ensureProlog();
+                }
+                if (!prolog) {
+                    ownedEngine = new EngineClient({
+                        workspaceRoot: context.workspaceRoot,
+                        branch: attachment.kbBranch,
+                        timeout: 15_000,
+                    });
+                    prolog = ownedEngine;
+                }
+                payload = await runOperationJsonQuery(prolog, "status.pl", "status:kb_status_json(JsonString)", "Status execution", context.signal);
                 if (!isStatusPayload(payload)) {
                     throw new Error("Status execution query returned an invalid payload");
                 }
@@ -227,6 +256,7 @@ export async function executeStatus(_input, context) {
         const existingReasons = payload.staleReasons ?? [];
         const storeReason = branchStoreReason(store);
         const lockReason = storeLockJournalReason(store.path);
+        const compilerReason = compilerFingerprintReason(store.path);
         const engineReason = engineStatus
             ? {
                 code: engineStatus.errorCode ?? "engine_status_unavailable",
@@ -244,10 +274,14 @@ export async function executeStatus(_input, context) {
             ...existingReasons,
             ...(storeReason ? [storeReason] : []),
             ...(lockReason ? [lockReason] : []),
+            ...(compilerReason ? [compilerReason] : []),
             ...(engineReason ? [engineReason] : []),
         ].sort((left, right) => String(left.path ?? "").localeCompare(String(right.path ?? "")));
         const enrichedPayload = {
             ...payload,
+            // Source hashes can all match while the compilation itself is lossy, so
+            // a compiler contract change alone makes the store stale.
+            ...(compilerReason ? { syncState: "stale", dirty: true } : {}),
             branchAttachment: attachment,
             branchStore: store,
             ...(engineStatus ? { engineStatus } : {}),

package/dist/public/operations/migration-plan.d.ts

@@ -70,6 +70,8 @@ export declare function compareReadyActionIds(left: string, right: string, byId:
 export declare function buildMigrationPlan(input?: PlanInput): MigrationPlan;
 export declare function mergeMigrationPlans(plans: readonly MigrationPlan[]): MigrationPlan;
 export declare function migrationAction(input: Partial<MigrationAction> & Pick<MigrationAction, "id" | "code">): MigrationAction;
+/** Migration code for mechanical predicate namespace/alias repairs. */
+export declare const PREDICATE_SCHEMA_ALIGNMENT_CODE = "predicate_schema_alignment";
 export declare function buildActionsFromCheck(input: {
     violations?: readonly Readonly<Record<string, unknown>>[];
     qualityDiagnostics?: readonly Readonly<Record<string, unknown>>[];

package/dist/public/operations/migration-plan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migration-plan.d.ts","sourceRoot":"","sources":["../../../src/public/operations/migration-plan.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,sBAAsB,EAAG,wBAAiC,CAAC;AAExE,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,SAAS,CAAC;AACvD,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,QAAQ,GAAG,UAAU,GAAG,WAAW,CAAC;AAChF,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,UAAU,GAAG,UAAU,CAAC;AAErE,MAAM,MAAM,mBAAmB,GAC3B,QAAQ,CAAC;IACP,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC1C,CAAC,GACF,QAAQ,CAAC;IACP,IAAI,EAAE,KAAK,CAAC;IACZ,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC,CAAC,GACF,QAAQ,CAAC;IACP,IAAI,EAAE,QAAQ,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC,CAAC;AAEP,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EACJ,SAAS,GACT,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,WAAW,GACX,cAAc,GACd,QAAQ,GACR,UAAU,GACV,OAAO,GACP,SAAS,CAAC;IACd,KAAK,EAAE,oBAAoB,CAAC;IAC5B,MAAM,EAAE,eAAe,CAAC;IACxB,UAAU,EAAE,mBAAmB,CAAC;IAChC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,aAAa,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;IAC5D,cAAc,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;IAC7D,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC5C,cAAc,EAAE,OAAO,CAAC;IACxB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,mBAAmB,EAAE,SAAS,oBAAoB,EAAE,CAAC;CACtD,CAAC,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC;IACnC,OAAO,EAAE,OAAO,sBAAsB,CAAC;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,YAAY,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;IACvD,QAAQ,EAAE,QAAQ,CAAC;QACjB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;QACjC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;KAC3B,CAAC,CAAC;IACH,KAAK,EAAE,QAAQ,CAAC;QACd,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;QACpC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;QACrC,QAAQ,EAAE,OAAO,CAAC;KACnB,CAAC,CAAC;IACH,OAAO,EAAE,QAAQ,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,gBAAgB,EAAE,MAAM,CAAC;QACzB,kBAAkB,EAAE,MAAM,CAAC;QAC3B,oBAAoB,EAAE,MAAM,CAAC;QAC7B,iBAAiB,EAAE,MAAM,CAAC;QAC1B,mBAAmB,EAAE,MAAM,CAAC;QAC5B,oBAAoB,EAAE,MAAM,CAAC;KAC9B,CAAC,CAAC;IACH,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IACpC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC,CAAC,CAAC;AAEH,KAAK,SAAS,GAAG,QAAQ,CAAC;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC,CAAC;IAC9C,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,OAAO,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACrC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC,CAAC,CAAC;AAuBH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAIxD;AAeD,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,GACzC,MAAM,CAOR;AAuED,wBAAgB,kBAAkB,CAAC,KAAK,GAAE,SAAc,GAAG,aAAa,CAsCvE;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,SAAS,aAAa,EAAE,GAC9B,aAAa,CA0Bf;AA6BD,wBAAgB,eAAe,CAC7B,KAAK,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI,CAAC,eAAe,EAAE,IAAI,GAAG,MAAM,CAAC,GACrE,eAAe,CAEjB;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE;IAC3C,UAAU,CAAC,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;IAC1D,kBAAkB,CAAC,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;CACnE,GAAG,eAAe,EAAE,CAuDpB;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC/C,gBAAgB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACtD,GAAG,eAAe,EAAE,CAgFpB;AAED,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC;IAC9D,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,OAAO,CAAC;IACxB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC,CAAC;AAEH,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,MAAM,GACpB,qBAAqB,CA8BvB;AAwBD,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC5C,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACrD,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAChD,YAAY,CAAC,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;IAC5D,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,YAAY,CAAC,EAAE,qBAAqB,CAAC;CACtC,GAAG,aAAa,CA6MhB"}
+{"version":3,"file":"migration-plan.d.ts","sourceRoot":"","sources":["../../../src/public/operations/migration-plan.ts"],"names":[],"mappings":"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"}