kibi-cli 0.14.0 → 0.16.1

package/dist/commands/check.js

@@ -15,14 +15,15 @@
  You should have received a copy of the GNU Affero General Public License
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import * as path from "node:path";
 import { getBranchOverride, isCliTraceOrDebugEnabled } from "../env.js";
 import { extractFromManifest, extractFromManifestString, } from "../extractors/manifest.js";
 import { extractFromMarkdownString, } from "../extractors/markdown.js";
-import { PrologProcess, resolveKbPlPath } from "../prolog.js";
+import { PrologProcess } from "../prolog.js";
 import { escapeAtom, parseTriples, parseViolationRows, } from "../prolog/codec.js";
-import { collectFullKbQualityDiagnostics, createSemanticReviewDiagnostics, createSymbolGranularityDiagnostics, createSymbolQualityDiagnostics, hasBlockingImpactDiagnostics, } from "../public/impact-diagnostics.js";
+import { createSemanticReviewDiagnostics, createSymbolGranularityDiagnostics, createSymbolQualityDiagnostics, hasBlockingImpactDiagnostics, } from "../public/impact-diagnostics.js";
+import { executeCheck } from "../public/operations/check-executor.js";
 import { KIBI_NO_IMPACT_DECLARATION, KIBI_SYMBOLS_MANIFEST_PATH, } from "../traceability/evidence-model.js";
 import { getStagedFiles } from "../traceability/git-staged.js";
 import { validateStagedMarkdown } from "../traceability/markdown-validate.js";
@@ -34,21 +35,7 @@ import { cleanupTempKb, consultOverlay, createOverlayFacts, createTempKb, projec
 import { formatViolations as formatStagedViolations, validateStagedSymbols, } from "../traceability/validate.js";
 import { loadConfig } from "../utils/config.js";
 import { safeCleanupProlog } from "../utils/prolog-cleanup.js";
-import { analyzePrologQueryPlanSafety } from "../utils/prolog-query-plan-safety.js";
-import { RULES, getEffectiveRules, } from "../utils/rule-registry.js";
-import { runAggregatedChecks } from "./aggregated-checks.js";
 import { getCurrentBranch } from "./init-helpers.js";
-function collectQueryPlanSafetyViolations() {
-    const checksPlPath = path.join(path.dirname(resolveKbPlPath()), "checks.pl");
-    const source = readFileSync(checksPlPath, "utf8");
-    return analyzePrologQueryPlanSafety(source).map((violation) => ({
-        rule: "query-plan-safety",
-        entityId: violation.predicate,
-        description: violation.description,
-        suggestion: violation.suggestion,
-        source: `${checksPlPath}:${violation.line}`,
-    }));
-}
 function getMatchGroup(match, index = 1) {
     const value = match?.[index];
     return typeof value === "string" ? value : null;
@@ -58,6 +45,27 @@ function buildManifestLookup(stagedFiles) {
     const manifestResults = [];
     const authoredSymbolResults = [];
     const stagedAuthoredSymbolResults = [];
+    const makeLookupKey = (entry) => {
+        if (typeof entry.entity.id === "string" && entry.entity.id.length > 0) {
+            return `id:${entry.entity.id}`;
+        }
+        return `fallback:${entry.sourceFile ?? entry.entity.source ?? ""}\u0000${entry.entity.title}`;
+    };
+    const authoredSymbolIndexByKey = new Map();
+    const manifestResultIndexByKey = new Map();
+    const stagedAuthoredSymbolIndexByKey = new Map();
+    const upsertResult = (results, indexByKey, result, preferNew = false) => {
+        const key = makeLookupKey(result);
+        const existingIndex = indexByKey.get(key);
+        if (existingIndex === undefined) {
+            indexByKey.set(key, results.length);
+            results.push(result);
+            return;
+        }
+        if (preferNew) {
+            results[existingIndex] = result;
+        }
+    };
     // Pre-populate lookup from working-tree manifests so that code-only changes
     // (where symbols.yaml is not staged) still resolve to the correct symbol IDs
     // and relationships already defined on disk.
@@ -69,7 +77,7 @@ function buildManifestLookup(stagedFiles) {
             try {
                 const entries = extractFromManifest(absSymbolsPath);
                 for (const entry of entries) {
-                    authoredSymbolResults.push(entry);
+                    upsertResult(authoredSymbolResults, authoredSymbolIndexByKey, entry);
                     const sourceFile = entry.sourceFile || entry.entity.source || absSymbolsPath;
                     const key = `${sourceFile}:${entry.entity.title}`;
                     manifestLookup.set(key, {
@@ -107,22 +115,23 @@ function buildManifestLookup(stagedFiles) {
         try {
             const entries = extractFromManifestString(manifestFile.content ?? "", manifestFile.path);
             for (const entry of entries) {
-                manifestResults.push({
+                const authoredSymbolResult = {
                     entity: entry.entity,
                     relationships: entry.relationships,
                     ...(entry.sourceFile !== undefined
                         ? { sourceFile: entry.sourceFile }
                         : {}),
-                });
-                const authoredSymbolResult = {
+                };
+                const manifestResult = {
                     entity: entry.entity,
                     relationships: entry.relationships,
                     ...(entry.sourceFile !== undefined
                         ? { sourceFile: entry.sourceFile }
                         : {}),
                 };
-                authoredSymbolResults.push(authoredSymbolResult);
-                stagedAuthoredSymbolResults.push(authoredSymbolResult);
+                upsertResult(manifestResults, manifestResultIndexByKey, manifestResult, true);
+                upsertResult(authoredSymbolResults, authoredSymbolIndexByKey, authoredSymbolResult, true);
+                upsertResult(stagedAuthoredSymbolResults, stagedAuthoredSymbolIndexByKey, authoredSymbolResult);
                 const sourceFile = entry.sourceFile || entry.entity.source || manifestFile.path;
                 const key = `${sourceFile}:${entry.entity.title}`;
                 manifestLookup.set(key, {
@@ -325,12 +334,12 @@ function buildStagedKibiImpactEvidence(options) {
             rationale: parsedOverride.rationale ?? "",
         };
     }
-    if (stagedAuthoredSymbolsEvidence.entries.length > 0) {
+    if (stagedAuthoredSymbolsEvidence.changedEntityIds.length > 0) {
         resolvedKbArtifacts.push({
             kind: "symbols_manifest",
             path: stagedAuthoredSymbolsEvidence.path,
             entityTypes: ["symbol"],
-            entityIds: uniqueSorted(stagedAuthoredSymbolsEvidence.entries.flatMap((entry) => entry.entityIds)),
+            entityIds: stagedAuthoredSymbolsEvidence.changedEntityIds,
             sourcePaths: uniqueSorted(stagedAuthoredSymbolsEvidence.entries.map((entry) => entry.sourcePath)),
         });
     }
@@ -450,9 +459,8 @@ export async function checkCommand(options) {
                         .filter((artifact) => artifact.kind === "symbols_manifest")
                         .flatMap((artifact) => artifact.entityIds)
                     : []);
-                const stagedAuthoredSymbolSet = new Set(stagedAuthoredSymbolResults);
                 const stagedSourcePaths = new Set(sourceFiles.map((file) => file.path));
-                const activeGranularityResults = authoredSymbolResults.filter((result) => stagedAuthoredSymbolSet.has(result) ||
+                const activeGranularityResults = authoredSymbolResults.filter((result) => activeStagedSymbolEntityIds.has(result.entity.id) ||
                     (result.sourceFile !== undefined &&
                         stagedSourcePaths.has(result.sourceFile)));
                 stagedKibiDiagnostics.push(...createSymbolGranularityDiagnostics({
@@ -566,77 +574,27 @@ export async function checkCommand(options) {
             return { exitCode: 1 };
         }
         attached = true;
-        const violations = [];
-        const config = loadConfig(process.cwd());
-        const checksConfig = config.checks ?? {
-            rules: Object.fromEntries(RULES.map((r) => [r.name, true])),
-            symbolTraceability: { requireAdr: false },
-        };
-        const effectiveRules = getEffectiveRules(checksConfig.rules, options.rules);
-        // Helper to conditionally run a check by name
-        async function runCheck(name, fn, ...args) {
-            if (!effectiveRules.has(name))
-                return;
-            if (!prolog) {
-                throw new Error("Prolog process not initialized");
-            }
-            const res = await fn(prolog, ...args);
-            if (res?.length)
-                violations.push(...res);
-        }
         if (!prolog) {
             throw new Error("Prolog process not initialized");
         }
         const activeProlog = prolog;
-        // Use aggregated checks (single Prolog call) when possible for better performance
-        // This is significantly faster in Bun/Docker environments where one-shot mode
-        // spawns a new Prolog process for each query
-        const supportedRules = [
-            "must-priority-coverage",
-            "symbol-coverage",
-            "symbol-traceability",
-            "no-dangling-refs",
-            "no-cycles",
-            "required-fields",
-            "deprecated-adr-no-successor",
-            "domain-contradictions",
-            "strict-fact-shape",
-            "strict-req-fact-pairing",
-            "strict-readiness",
-            "query-plan-safety",
-        ];
-        const canUseAggregated = Array.from(effectiveRules).every((r) => supportedRules.includes(r));
-        if (canUseAggregated) {
-            // Fast path: single Prolog call returning all violations
-            // Pass the requireAdr option for symbol-traceability
-            const aggregatedViolations = await runAggregatedChecks(activeProlog, effectiveRules, checksConfig.symbolTraceability?.requireAdr ?? false);
-            violations.push(...aggregatedViolations);
-        }
-        else {
-            // Legacy path: individual checks for backward compatibility
-            await runCheck("must-priority-coverage", checkMustPriorityCoverage);
-            await runCheck("symbol-coverage", checkSymbolCoverage);
-            await runCheck("symbol-traceability", (p) => checkSymbolTraceability(p, checksConfig.symbolTraceability?.requireAdr ?? false));
-            await runCheck("no-dangling-refs", checkNoDanglingRefs);
-            await runCheck("no-cycles", checkNoCycles);
-            const allEntityIds = await getAllEntityIds(activeProlog);
-            if (effectiveRules.has("required-fields")) {
-                const requiredViolations = await checkRequiredFields(activeProlog, allEntityIds);
-                violations.push(...requiredViolations);
-            }
-            await runCheck("deprecated-adr-no-successor", checkDeprecatedAdrs);
-            await runCheck("domain-contradictions", checkDomainContradictions);
-            await runCheck("strict-fact-shape", checkStrictFactShape);
-            await runCheck("strict-req-fact-pairing", checkStrictReqFactPairing);
-            await runCheck("strict-readiness", checkStrictReadiness);
-        }
-        if (effectiveRules.has("query-plan-safety")) {
-            violations.push(...collectQueryPlanSafetyViolations());
-        }
-        const qualityDiagnostics = await collectFullKbQualityDiagnostics({
-            prolog: activeProlog,
-            hardViolationEntityIds: new Set(violations.map((violation) => violation.entityId)),
-        });
+        const rules = options.rules
+            ?.split(",")
+            .map((rule) => rule.trim())
+            .filter((rule) => rule.length > 0);
+        const result = await executeCheck(rules === undefined ? {} : { rules }, {
+            workspaceRoot: process.cwd(),
+            signal: new AbortController().signal,
+            clock: () => new Date(),
+            prolog: {
+                query: (goal) => activeProlog.query(goal),
+                nextSolution: async () => null,
+                invalidateCache: () => activeProlog.invalidateCache(),
+                save: () => activeProlog.query("kb_save"),
+            },
+        }, { collectFullQualityDiagnosticsForExplicitRules: true });
+        const violations = result.structuredContent?.violations ?? [];
+        const qualityDiagnostics = result.structuredContent?.qualityDiagnostics ?? [];
         if (options.format === "json") {
             printStructuredCheckResult({ violations, qualityDiagnostics });
             return { exitCode: violations.length === 0 ? 0 : 1 };

package/dist/commands/coverage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coverage.d.ts","sourceRoot":"","sources":["../../src/commands/coverage.ts"],"names":[],"mappings":"AAQA,UAAU,eAAe;IACvB,EAAE,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC/B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B;AAGD,wBAAsB,eAAe,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAgC7E"}
+{"version":3,"file":"coverage.d.ts","sourceRoot":"","sources":["../../src/commands/coverage.ts"],"names":[],"mappings":"AAMA,UAAU,eAAe;IACvB,EAAE,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC/B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B;AAGD,wBAAsB,eAAe,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAmB7E"}

package/dist/commands/coverage.js

@@ -1,24 +1,19 @@
-import { escapeAtom } from "../prolog/codec.js";
-import { printDiscoveryResult, resolveCurrentKbPath, runJsonModuleQuery, withPrologProcess, } from "./discovery-shared.js";
+import { coverageSpec } from "../public/operations/index.js";
+import { executeReportingSpec, printDiscoveryResult, } from "./discovery-shared.js";
 // implements REQ-002, REQ-003
 export async function coverageCommand(options) {
-    await withPrologProcess(async (prolog) => {
-        const kbPath = await resolveCurrentKbPath();
-        const by = options.by || "req";
-        const tags = options.tag
-            ? `[${options.tag
+    const result = await executeReportingSpec(coverageSpec, {
+        by: options.by ?? "req",
+        tags: options.tag
+            ? options.tag
                 .split(",")
                 .map((item) => item.trim())
                 .filter(Boolean)
-                .map((item) => `'${escapeAtom(item)}'`)
-                .join(",")}]`
-            : "[]";
-        const includePassing = options.includePassing ?? false;
-        const includeTransitive = options.includeTransitive ?? true;
-        const limit = Number.parseInt(options.limit || "100", 10);
-        const offset = Number.parseInt(options.offset || "0", 10);
-        const result = await runJsonModuleQuery(prolog, "discovery.pl", `discovery:coverage_report_json('${by}', ${tags}, ${includePassing}, ${includeTransitive}, ${limit}, ${offset}, JsonString)`, "coverage query failed", kbPath);
-        const summary = (result.summary ?? {});
-        printDiscoveryResult(options.format, result, `Coverage summary: ${summary.fullyCovered ?? 0} fully covered out of ${summary.total ?? 0}.`);
+            : [],
+        includePassing: options.includePassing ?? false,
+        includeTransitive: options.includeTransitive ?? true,
+        limit: Number.parseInt(options.limit || "100", 10),
+        offset: Number.parseInt(options.offset || "0", 10),
     });
+    printDiscoveryResult(options.format, result.structuredContent, result.content[0]?.text ?? "Coverage summary unavailable.");
 }

package/dist/commands/discovery-shared.d.ts

@@ -1,4 +1,5 @@
 import { PrologProcess, resolveKbPlPath } from "../prolog.js";
+import { type OperationSpec, type RuntimeOptions } from "../public/operations/index.js";
 export { renderCoverageTable } from "./discovery-table.js";
 export interface DiscoveryCommandOptions {
     format?: "json" | "table";
@@ -10,8 +11,8 @@ export interface DiscoveryDeps {
     }) => PrologProcess;
     resolveKbPl: typeof resolveKbPlPath;
 }
+export declare function executeReportingSpec<TInput, TOutput>(spec: OperationSpec<TInput, TOutput>, input: TInput, options?: RuntimeOptions): Promise<import("../public/operations/types.js").OperationResult<TOutput>>;
 export declare function withAttachedBranchProlog<T>(callback: (prolog: PrologProcess) => Promise<T>, deps?: Partial<DiscoveryDeps>): Promise<T>;
-export declare function withPrologProcess<T>(callback: (prolog: PrologProcess) => Promise<T>, deps?: Partial<DiscoveryDeps>): Promise<T>;
 export declare function resolveCurrentKbPath(): Promise<string>;
 export declare function resolveCoreModulePath(fileName: string, deps?: Partial<DiscoveryDeps>): string;
 export declare function runJsonModuleQuery<T>(prolog: PrologProcess, fileName: string, goal: string, errorLabel: string, kbPath?: string, deps?: Partial<DiscoveryDeps>): Promise<T>;

package/dist/commands/discovery-shared.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discovery-shared.d.ts","sourceRoot":"","sources":["../../src/commands/discovery-shared.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAM9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B;AAED,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,aAAa,CAAC;IAC3D,WAAW,EAAE,OAAO,eAAe,CAAC;CACrC;AAGD,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,QAAQ,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,EAC/C,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,OAAO,CAAC,CAAC,CAAC,CAmCZ;AAGD,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,QAAQ,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,EAC/C,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,OAAO,CAAC,CAAC,CAAC,CAmBZ;AAGD,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,MAAM,CAAC,CAS5D;AAGD,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,MAAM,CAGR;AAGD,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,OAAO,CAAC,CAAC,CAAC,CAwBZ;AAGD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,EACpC,UAAU,EAAE,OAAO,EACnB,YAAY,EAAE,MAAM,GACnB,IAAI,CAQN"}
+{"version":3,"file":"discovery-shared.d.ts","sourceRoot":"","sources":["../../src/commands/discovery-shared.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE9D,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,cAAc,EAEpB,MAAM,+BAA+B,CAAC;AAMvC,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B;AAED,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,aAAa,CAAC;IAC3D,WAAW,EAAE,OAAO,eAAe,CAAC;CACrC;AAGD,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,OAAO,EACxD,IAAI,EAAE,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,cAAmB,6EAG7B;AAGD,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,QAAQ,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,EAC/C,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,OAAO,CAAC,CAAC,CAAC,CAmCZ;AAID,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,MAAM,CAAC,CAS5D;AAGD,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,MAAM,CAGR;AAGD,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,OAAO,CAAC,CAAC,CAAC,CAwBZ;AAGD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,EACpC,UAAU,EAAE,OAAO,EACnB,YAAY,EAAE,MAAM,GACnB,IAAI,CAQN"}

package/dist/commands/discovery-shared.js

@@ -2,10 +2,16 @@ import path from "node:path";
 import { getBranchOverride } from "../env.js";
 import { PrologProcess, resolveKbPlPath } from "../prolog.js";
 import { escapeAtom } from "../prolog/codec.js";
+import { executeOperation, } from "../public/operations/index.js";
+import { createCliRuntime } from "../runtime/cli-runtime.js";
 import { safeCleanupProlog } from "../utils/prolog-cleanup.js";
 import { renderDiscoveryTable } from "./discovery-table.js";
 import { getCurrentBranch } from "./init-helpers.js";
 export { renderCoverageTable } from "./discovery-table.js";
+// implements REQ-kibi-operation-interface-parity
+export async function executeReportingSpec(spec, input, options = {}) {
+    return executeOperation(createCliRuntime(options), spec, input, options);
+}
 // implements REQ-003
 export async function withAttachedBranchProlog(callback, deps) {
     const createProlog = deps?.createProlog ?? ((opts) => new PrologProcess(opts));
@@ -35,24 +41,6 @@ export async function withAttachedBranchProlog(callback, deps) {
     }
 }
 // implements REQ-003
-export async function withPrologProcess(callback, deps) {
-    const createProlog = deps?.createProlog ?? ((opts) => new PrologProcess(opts));
-    const prolog = createProlog({ timeout: 120000 });
-    try {
-        await prolog.start();
-        // NOTE: useOneShotMode is an internal optimization flag on PrologProcess that
-        // forces single-query mode (start → query → terminate per call) instead of the
-        // default interactive session. It is not exposed in the public PrologProcess
-        // type because callers should not set it directly — only internal discovery
-        // helpers use it for lightweight one-shot queries that don't need session state.
-        prolog.useOneShotMode = true;
-        await prolog.query("set_prolog_flag(answer_write_options, [max_depth(0), spacing(next_argument)])");
-        return await callback(prolog);
-    }
-    finally {
-        await safeCleanupProlog(prolog);
-    }
-}
 // implements REQ-003
 export async function resolveCurrentKbPath() {
     let branch;

package/dist/commands/gaps.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gaps.d.ts","sourceRoot":"","sources":["../../src/commands/gaps.ts"],"names":[],"mappings":"AAQA,UAAU,WAAW;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B;AAGD,wBAAsB,WAAW,CAC/B,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC,CAyBf"}
+{"version":3,"file":"gaps.d.ts","sourceRoot":"","sources":["../../src/commands/gaps.ts"],"names":[],"mappings":"AAMA,UAAU,WAAW;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B;AAGD,wBAAsB,WAAW,CAC/B,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC,CAef"}

package/dist/commands/gaps.js

@@ -1,28 +1,24 @@
-import { escapeAtom } from "../prolog/codec.js";
-import { printDiscoveryResult, resolveCurrentKbPath, runJsonModuleQuery, withPrologProcess, } from "./discovery-shared.js";
+import { findGapsSpec } from "../public/operations/index.js";
+import { executeReportingSpec, printDiscoveryResult, } from "./discovery-shared.js";
 // implements REQ-002, REQ-003
 export async function gapsCommand(type, options) {
-    await withPrologProcess(async (prolog) => {
-        const kbPath = await resolveCurrentKbPath();
-        const missing = csvToPrologList(options.missingRel);
-        const present = csvToPrologList(options.presentRel);
-        const tags = csvToPrologList(options.tag);
-        const source = options.source ? `'${escapeAtom(options.source)}'` : "none";
-        const limit = Number.parseInt(options.limit || "100", 10);
-        const offset = Number.parseInt(options.offset || "0", 10);
-        const typeArg = type ? `'${escapeAtom(type)}'` : "none";
-        const result = await runJsonModuleQuery(prolog, "discovery.pl", `discovery:find_gaps_json(${typeArg}, ${missing}, ${present}, ${tags}, ${source}, ${limit}, ${offset}, JsonString)`, "gaps query failed", kbPath);
-        printDiscoveryResult(options.format, result, `Found ${result.count ?? 0} gap rows.`);
+    const result = await executeReportingSpec(findGapsSpec, {
+        ...(type === undefined ? {} : { type }),
+        missingRelationships: csvValues(options.missingRel),
+        presentRelationships: csvValues(options.presentRel),
+        tags: csvValues(options.tag),
+        ...(options.source === undefined ? {} : { sourceFile: options.source }),
+        limit: Number.parseInt(options.limit || "100", 10),
+        offset: Number.parseInt(options.offset || "0", 10),
     });
+    printDiscoveryResult(options.format, result.structuredContent, result.content[0]?.text ?? "No matching gaps found.");
 }
-function csvToPrologList(value) {
+function csvValues(value) {
     if (!value?.trim()) {
-        return "[]";
+        return [];
     }
-    return `[${value
+    return value
         .split(",")
         .map((item) => item.trim())
-        .filter(Boolean)
-        .map((item) => `'${escapeAtom(item)}'`)
-        .join(",")}]`;
+        .filter(Boolean);
 }

package/dist/commands/graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../src/commands/graph.ts"],"names":[],"mappings":"AAQA,UAAU,YAAY;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,UAAU,GAAG,UAAU,GAAG,MAAM,CAAC;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B;AAGD,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAiCvE"}
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../src/commands/graph.ts"],"names":[],"mappings":"AAMA,UAAU,YAAY;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,UAAU,GAAG,UAAU,GAAG,MAAM,CAAC;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B;AAGD,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBvE"}

package/dist/commands/graph.js

@@ -1,5 +1,5 @@
-import { escapeAtom } from "../prolog/codec.js";
-import { printDiscoveryResult, resolveCurrentKbPath, runJsonModuleQuery, withPrologProcess, } from "./discovery-shared.js";
+import { graphSpec } from "../public/operations/index.js";
+import { executeReportingSpec, printDiscoveryResult, } from "./discovery-shared.js";
 // implements REQ-002, REQ-003
 export async function graphCommand(options) {
     if (!options.from?.trim()) {
@@ -7,29 +7,23 @@ export async function graphCommand(options) {
         process.exitCode = 1;
         return;
     }
-    await withPrologProcess(async (prolog) => {
-        const kbPath = await resolveCurrentKbPath();
-        const seedIds = csvToPrologList(options.from);
-        const relationships = csvToPrologList(options.relationships);
-        const direction = options.direction || "outgoing";
-        const depth = Number.parseInt(options.depth || "1", 10);
-        const entityTypes = csvToPrologList(options.entityTypes);
-        const maxNodes = Number.parseInt(options.maxNodes || "200", 10);
-        const maxEdges = Number.parseInt(options.maxEdges || "500", 10);
-        const result = await runJsonModuleQuery(prolog, "discovery.pl", `discovery:graph_expand_json(${seedIds}, ${relationships}, '${direction}', ${depth}, ${entityTypes}, ${maxNodes}, ${maxEdges}, JsonString)`, "graph query failed", kbPath);
-        const nodes = Array.isArray(result.nodes) ? result.nodes.length : 0;
-        const edges = Array.isArray(result.edges) ? result.edges.length : 0;
-        printDiscoveryResult(options.format, result, `Graph traversal returned ${nodes} nodes and ${edges} edges.`);
+    const result = await executeReportingSpec(graphSpec, {
+        seedIds: csvValues(options.from),
+        relationships: csvValues(options.relationships),
+        direction: options.direction ?? "outgoing",
+        depth: Number.parseInt(options.depth || "1", 10),
+        entityTypes: csvValues(options.entityTypes),
+        maxNodes: Number.parseInt(options.maxNodes || "200", 10),
+        maxEdges: Number.parseInt(options.maxEdges || "500", 10),
     });
+    printDiscoveryResult(options.format, result.structuredContent, result.content[0]?.text ?? "Graph traversal returned no nodes.");
 }
-function csvToPrologList(value) {
+function csvValues(value) {
     if (!value?.trim()) {
-        return "[]";
+        return [];
     }
-    return `[${value
+    return value
         .split(",")
         .map((item) => item.trim())
-        .filter(Boolean)
-        .map((item) => `'${escapeAtom(item)}'`)
-        .join(",")}]`;
+        .filter(Boolean);
 }

package/dist/commands/query.d.ts

@@ -1,11 +1,11 @@
 interface QueryOptions {
-    id?: string;
-    tag?: string;
-    source?: string;
-    relationships?: string;
-    format?: "json" | "table";
-    limit?: string;
-    offset?: string;
+    readonly id?: string;
+    readonly tag?: string;
+    readonly source?: string;
+    readonly relationships?: string;
+    readonly format?: "json" | "table";
+    readonly limit?: string;
+    readonly offset?: string;
 }
 export declare function queryCommand(type: string | undefined, options: QueryOptions): Promise<{
     exitCode: number;

package/dist/commands/query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/commands/query.ts"],"names":[],"mappings":"AA4CA,UAAU,YAAY;IACpB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAGD,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA4K/B"}
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/commands/query.ts"],"names":[],"mappings":"AAqBA,UAAU,YAAY;IACpB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA+C/B"}