kibi-cli 2.0.0 → 2.2.0

package/dist/public/operations/migration-plan.js

@@ -197,6 +197,51 @@ function actionDefaults(input) {
 export function migrationAction(input) {
     return actionDefaults(input);
 }
+/**
+ * A predicate-schema-conformance finding whose repair is mechanical (move to
+ * the only matching schema namespace, rewrite declared aliases) becomes an
+ * automatic action carrying the exact kb_upsert input, so it is reviewable in
+ * the plan and replayable through either surface.
+ */
+// implements REQ-kibi-predicate-vocabulary-migration
+function predicateSchemaAlignmentAction(diagnostic) {
+    if (diagnostic.id !== "rule.predicate-schema-conformance")
+        return null;
+    const evidence = isRecord(diagnostic.evidence) ? diagnostic.evidence : null;
+    const repair = evidence !== null && isRecord(evidence.repair) ? evidence.repair : null;
+    if (repair === null ||
+        repair.type !== "fact" ||
+        typeof repair.id !== "string" ||
+        !isRecord(repair.properties)) {
+        return null;
+    }
+    return migrationAction({
+        id: `predicate-schema-alignment-${repair.id}`,
+        code: PREDICATE_SCHEMA_ALIGNMENT_CODE,
+        category: "semantic",
+        safety: "automatic",
+        autoApplicable: true,
+        invocation: { kind: "operation", name: "kb_upsert", input: repair },
+        affectedEntityIds: [repair.id],
+        affectedFiles: typeof diagnostic.source === "string" ? [diagnostic.source] : [],
+        postconditions: [
+            {
+                rule: "predicate-schema-conformance",
+                entityId: repair.id,
+                findings: 0,
+            },
+        ],
+        evidence: {
+            issue: evidence?.issue,
+            namespace: evidence?.namespace,
+            alignment: evidence?.alignment,
+            rewrites: evidence?.rewrites,
+        },
+    });
+}
+/** Migration code for mechanical predicate namespace/alias repairs. */
+export const PREDICATE_SCHEMA_ALIGNMENT_CODE = "predicate_schema_alignment";
+// implements REQ-agent-guided-migration-orchestration, REQ-kibi-predicate-vocabulary-migration
 export function buildActionsFromCheck(input) {
     const actions = [];
     for (const [index, violation] of (input.violations ?? []).entries()) {
@@ -225,6 +270,11 @@ export function buildActionsFromCheck(input) {
             ? diagnostic.suggestion
             : "Review this quality diagnostic.";
         const blocking = diagnostic.blocking === true;
+        const predicateRepair = predicateSchemaAlignmentAction(diagnostic);
+        if (predicateRepair !== null) {
+            actions.push(predicateRepair);
+            continue;
+        }
         actions.push(migrationAction({
             id: `diagnostic-${id}-${entityId || "workspace"}-${index + 1}`,
             code: `quality_${id}`,

package/dist/public/operations/predicate-schema-conformance.d.ts

@@ -0,0 +1,41 @@
+import { type ArgumentRewrite, type UndeclaredArgument } from "../../operations/modeling/predicate-vocabulary.js";
+import type { Violation } from "../../utils/rule-registry.js";
+import type { PrologPort } from "./runtime-types.js";
+type Entity = Readonly<Record<string, unknown>>;
+/**
+ * Exact kb_upsert input that repairs one predicate fact mechanically: move it
+ * to the only namespace whose schema matches, and/or replace alias spellings
+ * with their declared constants. Present only when nothing is left for review.
+ */
+export type PredicateFactRepair = Readonly<{
+    type: "fact";
+    id: string;
+    properties: Readonly<Record<string, unknown>>;
+}>;
+export type PredicateConformanceEvidence = Readonly<{
+    factId: string;
+    predicateName: string;
+    namespace: string;
+    arity: number;
+    issue: "missing_schema" | "undeclared_constant" | "alias_in_use";
+    schemaId: string | null;
+    alignment: Readonly<{
+        namespace: string;
+        schemaId: string;
+        origin: "project_local" | "built_in";
+    }> | null;
+    candidateNamespaces: readonly string[];
+    rewrites: readonly ArgumentRewrite[];
+    undeclared: readonly UndeclaredArgument[];
+    repair: PredicateFactRepair | null;
+}>;
+/**
+ * Predicate facts must match a schema (project-local, or the built-in catalog
+ * in the default namespace) with the same namespace, name, and arity, and
+ * must use declared constants where the schema closes an argument.
+ */
+export declare function evaluatePredicateSchemaConformance(facts: readonly Entity[]): Violation[];
+/** Load every fact once and evaluate predicate conformance. */
+export declare function collectPredicateSchemaConformanceViolations(prolog: Pick<PrologPort, "query">): Promise<Violation[]>;
+export {};
+//# sourceMappingURL=predicate-schema-conformance.d.ts.map

package/dist/public/operations/predicate-schema-conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"predicate-schema-conformance.d.ts","sourceRoot":"","sources":["../../../src/public/operations/predicate-schema-conformance.ts"],"names":[],"mappings":"AAmBA,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,kBAAkB,EAMxB,MAAM,mDAAmD,CAAC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAG9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAsBrD,KAAK,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAUhD;;;;GAIG;AAEH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC/C,CAAC,CAAC;AAGH,MAAM,MAAM,4BAA4B,GAAG,QAAQ,CAAC;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,gBAAgB,GAAG,qBAAqB,GAAG,cAAc,CAAC;IACjE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,QAAQ,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,eAAe,GAAG,UAAU,CAAC;KACtC,CAAC,GAAG,IAAI,CAAC;IACV,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;IACrC,UAAU,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAC1C,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAAC;CACpC,CAAC,CAAC;AA+FH;;;;GAIG;AAEH,wBAAgB,kCAAkC,CAChD,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,SAAS,EAAE,CA+Gb;AAgDD,+DAA+D;AAE/D,wBAAsB,2CAA2C,CAC/D,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC,SAAS,EAAE,CAAC,CAGtB"}

package/dist/public/operations/predicate-schema-conformance.js

@@ -0,0 +1,242 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ 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 { BUILT_IN_PREDICATE_SCHEMAS } from "../../operations/modeling/predicate-catalog.js";
+import { applyArgumentRewrites, predicateArgumentConformance, predicateCanonicalKey, predicateVocabularyErrors, predicateVocabularyFromEntity, } from "../../operations/modeling/predicate-vocabulary.js";
+import entitySchema from "../schemas/entity.js";
+import { loadEntitiesPaged } from "./discovery-entities.js";
+const RULE = "predicate-schema-conformance";
+/** Every property the public entity schema accepts. */
+const AUTHORED_FIELDS = new Set(Object.keys(entitySchema.properties));
+const DEFAULT_NAMESPACE = "default";
+/** Fields that belong to the compiled entity, not to an authored upsert. */
+const NON_AUTHORED_FIELDS = new Set([
+    "id",
+    "type",
+    "source",
+    "sourceFile",
+    "created_at",
+    "updated_at",
+    "links",
+    "relationships",
+]);
+function text(value) {
+    return typeof value === "string" && value.trim() !== ""
+        ? value.trim()
+        : undefined;
+}
+function strings(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === "string")
+        : [];
+}
+function sourceField(entity) {
+    const source = text(entity.source);
+    return source !== undefined ? { source } : {};
+}
+function namespaceOf(entity) {
+    return text(entity.predicate_namespace) ?? DEFAULT_NAMESPACE;
+}
+function signature(namespace, name, arity) {
+    return `${namespace}:${name}/${arity}`;
+}
+function schemaRefs(facts) {
+    const byName = new Map();
+    const add = (name, ref) => {
+        byName.set(name, [...(byName.get(name) ?? []), ref]);
+    };
+    for (const entity of facts) {
+        if (entity.fact_kind !== "predicate_schema")
+            continue;
+        const name = text(entity.predicate_name);
+        if (name === undefined)
+            continue;
+        add(name, {
+            schemaId: String(entity.id),
+            namespace: namespaceOf(entity),
+            origin: "project_local",
+            argumentNames: strings(entity.argument_names),
+            entity,
+        });
+    }
+    // Built-in catalog schemas carry no namespace: facts that use them live in
+    // the default namespace. A project-local schema with the same signature wins.
+    for (const schema of BUILT_IN_PREDICATE_SCHEMAS) {
+        add(schema.predicate_name, {
+            schemaId: schema.id,
+            namespace: DEFAULT_NAMESPACE,
+            origin: "built_in",
+            argumentNames: schema.argument_names,
+        });
+    }
+    return byName;
+}
+function authoredProperties(entity) {
+    // Keep only fields an upsert accepts. Query rows also carry relationship
+    // projections (relates_to, validates, ...) as strings or lists, which must
+    // never be replayed as entity properties.
+    return Object.fromEntries(Object.entries(entity).filter(([key, value]) => AUTHORED_FIELDS.has(key) &&
+        !NON_AUTHORED_FIELDS.has(key) &&
+        value !== null &&
+        value !== undefined));
+}
+function repairFor(fact, name, args, targetNamespace, rewrites) {
+    const nextArgs = applyArgumentRewrites(args, rewrites);
+    const properties = authoredProperties(fact);
+    const previousKey = predicateCanonicalKey(name, args);
+    const nextKey = predicateCanonicalKey(name, nextArgs);
+    if (targetNamespace !== null)
+        properties.predicate_namespace = targetNamespace;
+    if (rewrites.length > 0) {
+        properties.predicate_args = nextArgs;
+        properties.canonical_key = nextKey;
+        if (properties.title === `Predicate: ${previousKey}`) {
+            properties.title = `Predicate: ${nextKey}`;
+        }
+    }
+    return { type: "fact", id: String(fact.id), properties };
+}
+/**
+ * Predicate facts must match a schema (project-local, or the built-in catalog
+ * in the default namespace) with the same namespace, name, and arity, and
+ * must use declared constants where the schema closes an argument.
+ */
+// implements REQ-kibi-predicate-schema-conformance
+export function evaluatePredicateSchemaConformance(facts) {
+    const schemasByName = schemaRefs(facts);
+    const violations = [];
+    for (const schema of facts) {
+        if (schema.fact_kind !== "predicate_schema")
+            continue;
+        const errors = predicateVocabularyErrors(schema);
+        if (errors.length === 0)
+            continue;
+        violations.push({
+            rule: RULE,
+            entityId: String(schema.id),
+            description: `Predicate schema ${String(schema.id)} declares an invalid argument vocabulary: ${errors.join("; ")}`,
+            suggestion: "Key argument_constants and argument_aliases by argument_names, and map every alias to a declared constant.",
+            ...sourceField(schema),
+            evidence: { schemaId: String(schema.id), errors },
+        });
+    }
+    for (const fact of facts) {
+        if (fact.fact_kind !== "predicate")
+            continue;
+        const name = text(fact.predicate_name);
+        const args = strings(fact.predicate_args);
+        if (name === undefined || args.length === 0)
+            continue;
+        const namespace = namespaceOf(fact);
+        const arity = args.length;
+        const sameShape = (schemasByName.get(name) ?? []).filter((ref) => ref.argumentNames.length === arity);
+        const exact = sameShape.find((ref) => ref.namespace === namespace && ref.origin === "project_local") ??
+            sameShape.find((ref) => ref.namespace === namespace && ref.origin === "built_in");
+        const candidates = [
+            ...new Map(sameShape
+                .filter((ref) => ref.namespace !== namespace)
+                .map((ref) => [ref.namespace, ref])).values(),
+        ];
+        const alignment = exact === undefined && candidates.length === 1
+            ? candidates[0]
+            : undefined;
+        const schema = exact ?? alignment;
+        const conformance = schema?.entity !== undefined
+            ? predicateArgumentConformance(schema.argumentNames, args, predicateVocabularyFromEntity(schema.entity))
+            : { rewrites: [], undeclared: [] };
+        if (exact !== undefined &&
+            conformance.rewrites.length === 0 &&
+            conformance.undeclared.length === 0) {
+            continue;
+        }
+        const issue = exact === undefined
+            ? "missing_schema"
+            : conformance.undeclared.length > 0
+                ? "undeclared_constant"
+                : "alias_in_use";
+        const mechanical = schema !== undefined && conformance.undeclared.length === 0;
+        const evidence = {
+            factId: String(fact.id),
+            predicateName: name,
+            namespace,
+            arity,
+            issue,
+            schemaId: exact?.schemaId ?? null,
+            alignment: alignment !== undefined
+                ? {
+                    namespace: alignment.namespace,
+                    schemaId: alignment.schemaId,
+                    origin: alignment.origin,
+                }
+                : null,
+            candidateNamespaces: candidates.map((ref) => ref.namespace).sort(),
+            rewrites: conformance.rewrites,
+            undeclared: conformance.undeclared,
+            repair: mechanical
+                ? repairFor(fact, name, args, alignment?.namespace ?? null, conformance.rewrites)
+                : null,
+        };
+        violations.push({
+            rule: RULE,
+            entityId: String(fact.id),
+            description: conformanceDescription(evidence),
+            suggestion: conformanceSuggestion(evidence),
+            ...sourceField(fact),
+            evidence,
+        });
+    }
+    return violations;
+}
+function conformanceDescription(evidence) {
+    const where = signature(evidence.namespace, evidence.predicateName, evidence.arity);
+    const parts = [];
+    if (evidence.issue === "missing_schema") {
+        parts.push(evidence.alignment !== null
+            ? `Predicate fact ${evidence.factId} uses ${where}, but its schema ${evidence.alignment.schemaId} is in namespace ${evidence.alignment.namespace}`
+            : evidence.candidateNamespaces.length > 1
+                ? `Predicate fact ${evidence.factId} uses ${where}; schemas with this signature exist in several namespaces (${evidence.candidateNamespaces.join(", ")})`
+                : `Predicate fact ${evidence.factId} uses ${where}, which has no predicate_schema`);
+    }
+    else {
+        parts.push(`Predicate fact ${evidence.factId} (${where})`);
+    }
+    for (const rewrite of evidence.rewrites) {
+        parts.push(`argument ${rewrite.argumentName} uses alias ${rewrite.from} for ${rewrite.to}`);
+    }
+    for (const value of evidence.undeclared) {
+        parts.push(`argument ${value.argumentName} value ${value.value} is not a declared constant (${value.allowed.join(", ")})`);
+    }
+    return parts.join("; ");
+}
+function conformanceSuggestion(evidence) {
+    if (evidence.repair !== null) {
+        return "Mechanical repair available: review and apply it with kibi migrate --apply-safe (or replay the kb_upsert in the migration action).";
+    }
+    if (evidence.undeclared.length > 0) {
+        return "Use a declared constant, add the value to argument_constants, or map it with argument_aliases so kibi migrate can rewrite it.";
+    }
+    if (evidence.candidateNamespaces.length > 1) {
+        return "Set predicate_namespace to the schema this claim belongs to.";
+    }
+    return "Declare a predicate_schema for this signature (kb_suggest_predicates helps pick an existing one) or move the claim to a schema that already exists.";
+}
+/** Load every fact once and evaluate predicate conformance. */
+// implements REQ-kibi-predicate-schema-conformance
+export async function collectPredicateSchemaConformanceViolations(prolog) {
+    const facts = await loadEntitiesPaged(prolog, "fact");
+    return evaluatePredicateSchemaConformance(facts);
+}

package/dist/public/operations/prolog-json.d.ts

@@ -13,7 +13,7 @@ export declare class OperationJsonDecodeError extends Error {
     readonly prefixCodePoints: readonly number[];
     constructor(errorLabel: string, stage: JsonBindingDecodeStage, rawJson: unknown, cause: unknown);
 }
-export declare function runOperationJsonQuery<T>(prolog: PrologPort, fileName: string, goal: string, errorLabel: string): Promise<T>;
+export declare function runOperationJsonQuery<T>(prolog: PrologPort, fileName: string, goal: string, errorLabel: string, signal?: AbortSignal): Promise<T>;
 export declare function toPrologAtom(value?: string): string;
 export declare function toPrologList(values?: readonly string[]): string;
 //# sourceMappingURL=prolog-json.d.ts.map

package/dist/public/operations/prolog-json.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prolog-json.d.ts","sourceRoot":"","sources":["../../../src/public/operations/prolog-json.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,MAAM,MAAM,sBAAsB,GAAG,OAAO,GAAG,OAAO,CAAC;AAEvD;;;;;GAKG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,QAAQ,CAAC,IAAI,gCAAgC;IAC7C,QAAQ,CAAC,KAAK,EAAE,sBAAsB,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;gBAG3C,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,sBAAsB,EAC7B,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,OAAO;CAiBjB;AAUD,wBAAsB,qBAAqB,CAAC,CAAC,EAC3C,MAAM,EAAE,UAAU,EAClB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,CAAC,CAAC,CAqDZ;AAiBD,wBAAgB,YAAY,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAInD;AAED,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAI/D"}
+{"version":3,"file":"prolog-json.d.ts","sourceRoot":"","sources":["../../../src/public/operations/prolog-json.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,MAAM,MAAM,sBAAsB,GAAG,OAAO,GAAG,OAAO,CAAC;AAEvD;;;;;GAKG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,QAAQ,CAAC,IAAI,gCAAgC;IAC7C,QAAQ,CAAC,KAAK,EAAE,sBAAsB,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;gBAG3C,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,sBAAsB,EAC7B,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,OAAO;CAiBjB;AAUD,wBAAsB,qBAAqB,CAAC,CAAC,EAC3C,MAAM,EAAE,UAAU,EAClB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,CAAC,CAAC,CAiEZ;AAkBD,wBAAgB,YAAY,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAInD;AAED,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAI/D"}

package/dist/public/operations/prolog-json.js

@@ -30,23 +30,29 @@ function resolveCoreModulePath(fileName) {
     const genericOverride = getKbPlPathOverride();
     return path.join(path.dirname(genericOverride ?? resolveKbPlPath()), fileName);
 }
-export async function runOperationJsonQuery(prolog, fileName, goal, errorLabel) {
+export async function runOperationJsonQuery(prolog, fileName, goal, errorLabel, signal) {
     const modulePath = escapeAtom(resolveCoreModulePath(fileName).replaceAll("\\", "/"));
     // Loading a module and invoking its predicate in one interactive goal makes
     // SWI reject `use_module/1` under the engine's guarded `once/1` wrapper, so
-    // use two serialized requests for production and retain the combined goal
-    // only for the repository's Bun-based one-shot tests.
+    // an interactive port gets two serialized requests. That split is only
+    // sound when both requests reach the same live session: the engine daemon
+    // guarantees it by recycling a lost session with every loaded module
+    // restored, and a started PrologProcess fails loudly once its session is
+    // lost. Any port whose queries run in isolated processes (an unstarted or
+    // one-shot PrologProcess reports `oneShotMode`) must receive the combined
+    // goal, or the module load and the predicate call land in different SWI
+    // processes and the call fails with an existence error.
     const longLivedEngine = typeof prolog.storageStatus === "function";
-    const oneShotMode = prolog.oneShotMode === true ||
+    const oneShotMode = prolog.oneShotMode ??
         (!longLivedEngine &&
             process.env.NODE_ENV === "test" &&
             typeof globalThis.Bun !== "undefined");
     const typedStatusQuery = prolog.queryStatusJson;
     const result = fileName === "status.pl" && typeof typedStatusQuery === "function"
-        ? await typedStatusQuery.call(prolog)
+        ? await typedStatusQuery.call(prolog, signal)
         : oneShotMode
-            ? await prolog.query(`(use_module('${modulePath}'), ${goal})`)
-            : await runInteractiveModuleQuery(prolog, modulePath, goal, errorLabel);
+            ? await prolog.query(`(use_module('${modulePath}'), ${goal})`, signal)
+            : await runInteractiveModuleQuery(prolog, modulePath, goal, errorLabel, signal);
     if (!result.success) {
         throw new Error(`${errorLabel} query failed: ${result.error ?? "Unknown error"}`);
     }
@@ -74,12 +80,12 @@ export async function runOperationJsonQuery(prolog, fileName, goal, errorLabel)
     }
     return parsed;
 }
-async function runInteractiveModuleQuery(prolog, modulePath, goal, errorLabel) {
-    const loadResult = await prolog.query(`use_module('${modulePath}')`);
+async function runInteractiveModuleQuery(prolog, modulePath, goal, errorLabel, signal) {
+    const loadResult = await prolog.query(`use_module('${modulePath}')`, signal);
     if (!loadResult.success) {
         throw new Error(`${errorLabel} module load failed: ${loadResult.error ?? "Unknown error"}`);
     }
-    return prolog.query(goal);
+    return prolog.query(goal, signal);
 }
 export function toPrologAtom(value) {
     return value === undefined || value === ""

package/dist/public/operations/result-envelope.d.ts

@@ -9,6 +9,39 @@ export declare function toKibiResult<T>(spec: {
     readonly name: OperationName | string;
     readonly effects: readonly OperationEffect[];
     readonly resultVersion?: string;
-}, data: T, options?: Partial<Pick<KibiResult<T>, "status" | "diagnostics" | "nextActions" | "error">>): KibiResult<T>;
+}, data: T, options?: Partial<Pick<KibiResult<T>, "status" | "diagnostics" | "nextActions" | "error">> & {
+    /**
+     * False when the operation was rejected before it ran (invalid input),
+     * so an error envelope reports its effects as not applicable rather than
+     * failed.
+     */
+    readonly attempted?: boolean;
+}): KibiResult<T>;
 export declare function operationData(value: unknown): unknown;
+export interface NormalizedResultPayload {
+    /** The versioned KibiResult envelope, when the result carries one. */
+    readonly envelope?: Record<string, unknown>;
+    /** The operation payload that operation-specific telemetry fields read. */
+    readonly data?: Record<string, unknown>;
+}
+/**
+ * Resolve a tool result into its envelope and its operation payload.
+ *
+ * Callers hand results over in two shapes: MCP tool handlers pass the bare
+ * `toKibiResult` envelope, while some CLI and SDK routes wrap it as
+ * `{ structuredContent }`.  Deriving telemetry from the wrong shape silently
+ * yields an absent payload, so both shapes resolve here instead of at each
+ * call site.  An unresolvable payload stays `undefined` so callers can record
+ * the count as unknown rather than as zero.
+ */
+export declare function normalizeResultPayload(result: unknown): NormalizedResultPayload;
+/**
+ * Record a count that could not be read as unknown rather than as zero.
+ *
+ * A missing payload and an empty result are different facts, and collapsing
+ * them hides retrieval failures behind a plausible "0 results" row. Both the
+ * MCP and CLI diagnostic loggers derive counts here so the two surfaces stay
+ * at parity.
+ */
+export declare function appendPayloadCountField(fields: Record<string, unknown>, countKey: string, noun: string, payload: Record<string, unknown> | undefined): void;
 //# sourceMappingURL=result-envelope.d.ts.map

package/dist/public/operations/result-envelope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"result-envelope.d.ts","sourceRoot":"","sources":["../../../src/public/operations/result-envelope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE7E,eAAO,MAAM,qBAAqB,EAAG,CAAU,CAAC;AAoChD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,UAAU,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAS/B;AA6CD,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAClC,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAAC;IACtC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC,GAAG,MAAM,CAET;AAED,wBAAgB,YAAY,CAAC,CAAC,EAC5B,IAAI,EAAE;IACJ,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC,EACD,IAAI,EAAE,CAAC,EACP,OAAO,GAAE,OAAO,CACd,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,QAAQ,GAAG,aAAa,GAAG,aAAa,GAAG,OAAO,CAAC,CACnE,GACL,UAAU,CAAC,CAAC,CAAC,CAqBf;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAKrD"}
+{"version":3,"file":"result-envelope.d.ts","sourceRoot":"","sources":["../../../src/public/operations/result-envelope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE7E,eAAO,MAAM,qBAAqB,EAAG,CAAU,CAAC;AAoChD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,UAAU,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAS/B;AAoFD,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAClC,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAAC;IACtC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC,GAAG,MAAM,CAET;AAED,wBAAgB,YAAY,CAAC,CAAC,EAC5B,IAAI,EAAE;IACJ,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC,EACD,IAAI,EAAE,CAAC,EACP,OAAO,GAAE,OAAO,CACd,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,QAAQ,GAAG,aAAa,GAAG,aAAa,GAAG,OAAO,CAAC,CACxE,GAAG;IACF;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CACzB,GACL,UAAU,CAAC,CAAC,CAAC,CAsBf;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAKrD;AAGD,MAAM,WAAW,uBAAuB;IACtC,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,OAAO,GACd,uBAAuB,CAYzB;AAaD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC3C,IAAI,CAKN"}

package/dist/public/operations/result-envelope.js

@@ -41,13 +41,39 @@ export function failedEffectStatus(effect, failure) {
             : {}),
     };
 }
-function effectStatus(effect, data) {
+function effectOutcome(status, options) {
+    if (status !== "error")
+        return { kind: "completed" };
+    if (options.attempted === false)
+        return { kind: "not_attempted" };
+    return options.error
+        ? { kind: "failed", errorCode: options.error.code }
+        : { kind: "failed" };
+}
+function effectStatus(effect, data, outcome) {
     const failures = data?.effectFailures;
     if (Array.isArray(failures)) {
         const failure = failures.find((entry) => record(entry) && entry.kind === effect);
         if (record(failure))
             return failedEffectStatus(effect, failure);
     }
+    // A plan-only result declares the effects it left to a later call.
+    if (Array.isArray(data?.skippedEffects) &&
+        data.skippedEffects.includes(effect)) {
+        return { kind: effect, status: "not_applicable" };
+    }
+    // An error envelope must never claim a declared effect completed: the
+    // operation either never ran or stopped before reporting its effects.
+    if (outcome.kind === "not_attempted") {
+        return { kind: effect, status: "not_applicable" };
+    }
+    if (outcome.kind === "failed") {
+        return {
+            kind: effect,
+            status: "failed",
+            ...(outcome.errorCode ? { errorCode: outcome.errorCode } : {}),
+        };
+    }
     return { kind: effect, status: "completed" };
 }
 function extraFailedEffects(declared, data) {
@@ -83,6 +109,7 @@ export function toKibiResult(spec, data, options = {}) {
         (row?.status === "committed_with_repairs"
             ? "committed_with_repairs"
             : "success");
+    const outcome = effectOutcome(status, options);
     return {
         kibiProtocol: KIBI_PROTOCOL_VERSION,
         operation: spec.name,
@@ -90,7 +117,7 @@ export function toKibiResult(spec, data, options = {}) {
         status,
         data,
         effects: [
-            ...spec.effects.map((effect) => effectStatus(effect, row)),
+            ...spec.effects.map((effect) => effectStatus(effect, row, outcome)),
             ...extraFailedEffects(spec.effects, row),
         ],
         diagnostics: options.diagnostics ?? diagnostics(row?.diagnostics),
@@ -104,3 +131,52 @@ export function operationData(value) {
     }
     return value;
 }
+/**
+ * Resolve a tool result into its envelope and its operation payload.
+ *
+ * Callers hand results over in two shapes: MCP tool handlers pass the bare
+ * `toKibiResult` envelope, while some CLI and SDK routes wrap it as
+ * `{ structuredContent }`.  Deriving telemetry from the wrong shape silently
+ * yields an absent payload, so both shapes resolve here instead of at each
+ * call site.  An unresolvable payload stays `undefined` so callers can record
+ * the count as unknown rather than as zero.
+ */
+export function normalizeResultPayload(result) {
+    if (!record(result))
+        return {};
+    const candidate = record(result.structuredContent)
+        ? result.structuredContent
+        : result;
+    if (candidate.kibiProtocol !== KIBI_PROTOCOL_VERSION) {
+        return { data: candidate };
+    }
+    return {
+        envelope: candidate,
+        ...(record(candidate.data) ? { data: candidate.data } : {}),
+    };
+}
+function readPayloadCount(raw) {
+    if (typeof raw === "number")
+        return Number.isFinite(raw) ? raw : null;
+    // Some transports serialize counts as strings; an absent or unparseable
+    // value stays null so it is never coerced to a plausible zero.
+    if (typeof raw === "string" && raw.trim() !== "") {
+        const parsed = Number(raw);
+        return Number.isFinite(parsed) ? parsed : null;
+    }
+    return null;
+}
+/**
+ * Record a count that could not be read as unknown rather than as zero.
+ *
+ * A missing payload and an empty result are different facts, and collapsing
+ * them hides retrieval failures behind a plausible "0 results" row. Both the
+ * MCP and CLI diagnostic loggers derive counts here so the two surfaces stay
+ * at parity.
+ */
+export function appendPayloadCountField(fields, countKey, noun, payload) {
+    const count = readPayloadCount(payload?.count);
+    fields[countKey] = count;
+    fields.result_summary =
+        count === null ? `${noun} count unavailable` : `${count} ${noun}`;
+}

package/dist/public/operations/runtime-types.d.ts

@@ -1,7 +1,11 @@
+import type { CapabilityRegistry } from "../../plugins/registry.js";
 import type { PrologErrorRecord } from "../../prolog/error-terms.js";
 import type { BranchAttachment } from "../../utils/branch-resolver.js";
 import type { OperationEffect } from "./types.js";
 export type { OperationEffect } from "./types.js";
+export type { CapabilityRegistry } from "../../plugins/registry.js";
+/** Lazy or pre-materialized capability-plugin registry for an operation. */
+export type OperationPlugins = CapabilityRegistry | (() => Promise<CapabilityRegistry>);
 export type PrologQueryResult = {
     readonly success: boolean;
     readonly bindings: Readonly<Record<string, string>>;
@@ -107,7 +111,7 @@ export interface PrologPort {
     /** Present on the journaled engine; used to distinguish a persistent port from one-shot SWI. */
     storageStatus?(): Promise<PrologQueryResult>;
     /** Typed public freshness query; avoids exposing module loading over RPC. */
-    queryStatusJson?(): Promise<PrologQueryResult>;
+    queryStatusJson?(signal?: AbortSignal): Promise<PrologQueryResult>;
 }
 export type FilesystemStat = {
     readonly isFile: () => boolean;
@@ -160,6 +164,8 @@ export type RuntimeOptions = {
     readonly fs?: FilesystemPort;
     readonly git?: GitPort;
     readonly net?: NetworkPort;
+    /** Optional injectable capability registry (or lazy factory). */
+    readonly plugins?: OperationPlugins;
 };
 export type OperationContext = {
     readonly workspaceRoot: string;
@@ -174,16 +180,25 @@ export type OperationContext = {
     readonly sourceFirst?: boolean;
     /** Internal apply-plan capability: source bytes were already approved/published. */
     readonly sourcePlanApplication?: boolean;
-    /** Internal apply-plan capability: caller holds the cooperative source lock. */
+    /** Internal operation capability: a parent operation holds the source lock. */
     readonly sourceMutationLockHeld?: boolean;
     readonly git?: GitPort;
     readonly net?: NetworkPort;
     readonly branchAttachment?: BranchAttachment;
+    /** Pre-materialized or lazy capability registry supplied by the host runtime. */
+    readonly plugins?: OperationPlugins;
+    /** Lazily materialize the workspace capability registry. */
+    readonly ensurePlugins?: () => Promise<CapabilityRegistry>;
 };
 export interface RuntimeOperationSpec<TInput = unknown, TResult = unknown> {
     readonly name: string;
     readonly effects: readonly OperationEffect[];
     readonly requiresProlog: boolean;
+    /**
+     * When true, MCP embeds envelope `data` JSON in tool `content` for hosts that
+     * hide `structuredContent` (discovery/proof lookup). Default false.
+     */
+    readonly agentVisibleStructuredData?: boolean;
     execute(input: TInput, context: OperationContext): Promise<TResult>;
 }
 export type OperationOutcome = {