kibi-cli 2.0.0 → 2.2.0

package/dist/plugins/compose-vocabulary-alignment.js

@@ -0,0 +1,141 @@
+/*
+ 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 { NEW_SUBJECT_CHOICE, validateCompareClaimsResult, validateRankSubjectsResult, } from "kibi-plugin-sdk";
+import { diagnosticFromError, withFallback, } from "./compose-semantic-classifier.js";
+import { allowsExternalVocabularyAlignment } from "./external-allowlist.js";
+async function attempt(binding, strategy, input) {
+    try {
+        return { ok: true, results: await strategy.run(binding.capability, input) };
+    }
+    catch (error) {
+        return { ok: false, diagnostic: diagnosticFromError(binding, error) };
+    }
+}
+function mergeByKey(strategy, input, primary, fallback) {
+    const primaryByKey = new Map(primary.map((r) => [strategy.keyOf(r), r]));
+    const fallbackByKey = new Map(fallback.map((r) => [strategy.keyOf(r), r]));
+    return strategy.itemKeys(input).flatMap((key) => {
+        const result = primaryByKey.get(key) ?? fallbackByKey.get(key);
+        return result === undefined ? [] : [result];
+    });
+}
+/**
+ * replace / augment / shadow with the same semantics as the semantic
+ * classifier: a replace provider owns the result and falls back to builtin
+ * (stamped fallbackUsed) on any failure; augment providers only refine items
+ * the builtin left unresolved; shadow providers are recorded for comparison
+ * and never change the result. External providers run only for allowlisted
+ * operations.
+ */
+async function compose(resolution, strategy, input, operationName) {
+    const allowExternal = allowsExternalVocabularyAlignment(operationName);
+    const stamps = [];
+    const diagnostics = [];
+    const shadowComparisons = [];
+    let fallbackUsed = false;
+    let results = [];
+    const builtin = await attempt(resolution.builtin, strategy, input);
+    const builtinResults = builtin.ok ? builtin.results : [];
+    if (allowExternal && resolution.replace) {
+        const replaced = await attempt(resolution.replace, strategy, input);
+        if (replaced.ok) {
+            results = mergeByKey(strategy, input, replaced.results, builtinResults);
+            stamps.push(resolution.replace.stamp);
+        }
+        else {
+            diagnostics.push(replaced.diagnostic);
+            fallbackUsed = true;
+            if (builtin.ok) {
+                results = [...builtinResults];
+                stamps.push(withFallback(resolution.builtin.stamp, true));
+            }
+            else {
+                diagnostics.push(builtin.diagnostic);
+            }
+        }
+    }
+    else {
+        if (builtin.ok) {
+            results = [...builtinResults];
+            stamps.push(resolution.builtin.stamp);
+        }
+        else {
+            diagnostics.push(builtin.diagnostic);
+        }
+        if (allowExternal) {
+            for (const augment of resolution.augment) {
+                const unresolved = new Set(results.filter(strategy.unresolved).map(strategy.keyOf));
+                if (unresolved.size === 0)
+                    break;
+                const augmented = await attempt(augment, strategy, strategy.subset(input, unresolved));
+                if (!augmented.ok) {
+                    diagnostics.push(augmented.diagnostic);
+                    continue;
+                }
+                stamps.push(augment.stamp);
+                const improvements = augmented.results.filter((result) => unresolved.has(strategy.keyOf(result)) && strategy.improves(result));
+                results = mergeByKey(strategy, input, improvements, results);
+            }
+        }
+    }
+    if (allowExternal) {
+        for (const shadow of resolution.shadow) {
+            const shadowed = await attempt(shadow, strategy, input);
+            if (!shadowed.ok) {
+                diagnostics.push(shadowed.diagnostic);
+                continue;
+            }
+            stamps.push(shadow.stamp);
+            shadowComparisons.push({
+                stamp: shadow.stamp,
+                results: shadowed.results,
+            });
+        }
+    }
+    return { results, stamps, shadowComparisons, fallbackUsed, diagnostics };
+}
+const RANK_SUBJECTS = {
+    keyOf: (decision) => decision.claimKey,
+    itemKeys: (input) => input.clauses.map((clause) => clause.claimKey),
+    subset: (input, keys) => ({
+        clauses: input.clauses.filter((clause) => keys.has(clause.claimKey)),
+    }),
+    run: async (provider, input) => validateRankSubjectsResult(await provider.rankSubjects(input), input.clauses).decisions,
+    unresolved: (decision) => decision.choice === NEW_SUBJECT_CHOICE,
+    improves: (decision) => decision.choice !== NEW_SUBJECT_CHOICE,
+};
+const COMPARE_CLAIMS = {
+    keyOf: (judgment) => judgment.pairKey,
+    itemKeys: (input) => input.pairs.map((pair) => pair.pairKey),
+    subset: (input, keys) => ({
+        pairs: input.pairs.filter((pair) => keys.has(pair.pairKey)),
+    }),
+    run: async (provider, input) => validateCompareClaimsResult(await provider.compareClaims(input), input.pairs.map((pair) => pair.pairKey)).judgments,
+    unresolved: (judgment) => !judgment.sameObligation,
+    improves: (judgment) => judgment.sameObligation,
+};
+/** Choose an existing subject (or new_subject) for each clause. */
+// implements REQ-kibi-vocabulary-alignment-capability
+export function composeSubjectRanking(resolution, input, options) {
+    return compose(resolution, RANK_SUBJECTS, input, options.operationName);
+}
+/** Judge claim pairs; true judgments are review candidates, never verdicts. */
+// implements REQ-kibi-vocabulary-alignment-capability
+export function composeClaimComparison(resolution, input, options) {
+    return compose(resolution, COMPARE_CLAIMS, input, options.operationName);
+}

package/dist/plugins/external-allowlist.d.ts

@@ -0,0 +1,17 @@
+/**
+ * External capability plugins may be imported only from these operation
+ * boundaries. sync / check / validate-upsert / upsert / migration / status /
+ * proof / doctor / coverage / suggest-predicates must never import a
+ * third-party plugin module — allowlisting the classifier call is not enough.
+ */
+export declare const EXTERNAL_SEMANTIC_CLASSIFIER_OPERATIONS: readonly ["kb_semantic_advisor", "kb_compile_intent"];
+export type ExternalSemanticClassifierOperation = (typeof EXTERNAL_SEMANTIC_CLASSIFIER_OPERATIONS)[number];
+export declare function allowsExternalSemanticClassifier(operationName: string): boolean;
+/**
+ * Operations that may call external kibi.vocabulary-alignment.v1 providers.
+ * kb_check and every other operation stay builtin-only: vocabulary alignment is
+ * modeling-time advice and never participates in pass/fail checks.
+ */
+export declare const EXTERNAL_VOCABULARY_ALIGNMENT_OPERATIONS: readonly ["kb_model_requirement"];
+export declare function allowsExternalVocabularyAlignment(operationName: string): boolean;
+//# sourceMappingURL=external-allowlist.d.ts.map

package/dist/plugins/external-allowlist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-allowlist.d.ts","sourceRoot":"","sources":["../../src/plugins/external-allowlist.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,uCAAuC,uDAG1C,CAAC;AAGX,MAAM,MAAM,mCAAmC,GAC7C,CAAC,OAAO,uCAAuC,CAAC,CAAC,MAAM,CAAC,CAAC;AAK3D,wBAAgB,gCAAgC,CAC9C,aAAa,EAAE,MAAM,GACpB,OAAO,CAET;AAED;;;;GAIG;AAEH,eAAO,MAAM,wCAAwC,mCAE3C,CAAC;AAGX,wBAAgB,iCAAiC,CAC/C,aAAa,EAAE,MAAM,GACpB,OAAO,CAIT"}

package/dist/plugins/external-allowlist.js

@@ -0,0 +1,29 @@
+/**
+ * External capability plugins may be imported only from these operation
+ * boundaries. sync / check / validate-upsert / upsert / migration / status /
+ * proof / doctor / coverage / suggest-predicates must never import a
+ * third-party plugin module — allowlisting the classifier call is not enough.
+ */
+// implements REQ-capability-plugin-activation-disclosure-v1
+export const EXTERNAL_SEMANTIC_CLASSIFIER_OPERATIONS = [
+    "kb_semantic_advisor",
+    "kb_compile_intent",
+];
+const ALLOWED = new Set(EXTERNAL_SEMANTIC_CLASSIFIER_OPERATIONS);
+// implements REQ-capability-plugin-activation-disclosure-v1, REQ-capability-plugin-observable-behavior-v1
+export function allowsExternalSemanticClassifier(operationName) {
+    return ALLOWED.has(operationName);
+}
+/**
+ * Operations that may call external kibi.vocabulary-alignment.v1 providers.
+ * kb_check and every other operation stay builtin-only: vocabulary alignment is
+ * modeling-time advice and never participates in pass/fail checks.
+ */
+// implements REQ-kibi-vocabulary-alignment-capability
+export const EXTERNAL_VOCABULARY_ALIGNMENT_OPERATIONS = [
+    "kb_model_requirement",
+];
+// implements REQ-kibi-vocabulary-alignment-capability
+export function allowsExternalVocabularyAlignment(operationName) {
+    return EXTERNAL_VOCABULARY_ALIGNMENT_OPERATIONS.includes(operationName);
+}

package/dist/plugins/index.d.ts

@@ -0,0 +1,11 @@
+export { describeConfiguredCapabilityPlugins, readProjectKibiConfig, readProjectPackageJson, type ConfiguredCapabilityPluginDiagnostic, type ProjectPackageManifest, } from "./project-config.js";
+export { PluginResolutionError, PluginValidationError, assertBarePackageName, assertResolvedEntryInsidePackageRoot, hasConsumerNodeModulesLink, hasDeclaredProjectDependency, isBarePackageName, isProjectScopedPackage, packageJsonForResolvedFile, resolveProjectLocalPackage, type ResolvedProjectPackage, } from "./resolve-package.js";
+export { loadPluginPackage, type LoadPluginOptions, type LoadedPlugin, } from "./load-plugin.js";
+export { CapabilityRegistry, CapabilityRegistryCache, createCapabilityRegistry, createCapabilityRegistryCache, createStubBuiltinPlugin, ensureCapabilityRegistry, type BuiltinPluginFactory, type CapabilityModeResolution, type CapabilityProviderBinding, type CapabilityRegistryOptions, type EnsureCapabilityRegistryOptions, } from "./registry.js";
+export { composeSemanticClassification, publicCapabilityStamp, type ComposedSemanticClassifierResult, type SemanticClassifierDiagnostic, } from "./compose-semantic-classifier.js";
+export { composeOntologyCatalog, composeOntologyMatches, type ComposedOntologyCatalog, type StampedOntologyCandidate, } from "./compose-ontology-packs.js";
+export { SourceAnalysisService, analyzeWithResolution, createConservativeFallbackAnalysis, createSourceAnalysisService, type HostSourceAnalysisResult, type SourceAnalysisServiceOptions, } from "./source-analysis-service.js";
+export { EXTERNAL_SEMANTIC_CLASSIFIER_OPERATIONS, allowsExternalSemanticClassifier, type ExternalSemanticClassifierOperation, } from "./external-allowlist.js";
+export { composeClaimComparison, composeSubjectRanking, type ComposedVocabularyResult, type VocabularyAlignmentDiagnostic, } from "./compose-vocabulary-alignment.js";
+export { EXTERNAL_VOCABULARY_ALIGNMENT_OPERATIONS, allowsExternalVocabularyAlignment, } from "./external-allowlist.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/plugins/index.ts"],"names":[],"mappings":"AAmBA,OAAO,EACL,mCAAmC,EACnC,qBAAqB,EACrB,sBAAsB,EACtB,KAAK,oCAAoC,EACzC,KAAK,sBAAsB,GAC5B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,EACrB,oCAAoC,EACpC,0BAA0B,EAC1B,4BAA4B,EAC5B,iBAAiB,EACjB,sBAAsB,EACtB,0BAA0B,EAC1B,0BAA0B,EAC1B,KAAK,sBAAsB,GAC5B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,iBAAiB,EACjB,KAAK,iBAAiB,EACtB,KAAK,YAAY,GAClB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,wBAAwB,EACxB,6BAA6B,EAC7B,uBAAuB,EACvB,wBAAwB,EACxB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAC9B,KAAK,yBAAyB,EAC9B,KAAK,+BAA+B,GACrC,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,6BAA6B,EAC7B,qBAAqB,EACrB,KAAK,gCAAgC,EACrC,KAAK,4BAA4B,GAClC,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,GAC9B,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,kCAAkC,EAClC,2BAA2B,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,4BAA4B,GAClC,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EACL,uCAAuC,EACvC,gCAAgC,EAChC,KAAK,mCAAmC,GACzC,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,KAAK,wBAAwB,EAC7B,KAAK,6BAA6B,GACnC,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EACL,wCAAwC,EACxC,iCAAiC,GAClC,MAAM,yBAAyB,CAAC"}

package/dist/plugins/index.js

@@ -0,0 +1,37 @@
+/*
+ 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/>.
+*/
+// implements REQ-capability-plugin-activation-disclosure-v1
+export { describeConfiguredCapabilityPlugins, readProjectKibiConfig, readProjectPackageJson, } from "./project-config.js";
+// implements REQ-capability-plugin-activation-disclosure-v1
+export { PluginResolutionError, PluginValidationError, assertBarePackageName, assertResolvedEntryInsidePackageRoot, hasConsumerNodeModulesLink, hasDeclaredProjectDependency, isBarePackageName, isProjectScopedPackage, packageJsonForResolvedFile, resolveProjectLocalPackage, } from "./resolve-package.js";
+// implements REQ-capability-plugin-activation-disclosure-v1
+export { loadPluginPackage, } from "./load-plugin.js";
+// implements REQ-capability-plugin-activation-disclosure-v1
+export { CapabilityRegistry, CapabilityRegistryCache, createCapabilityRegistry, createCapabilityRegistryCache, createStubBuiltinPlugin, ensureCapabilityRegistry, } from "./registry.js";
+// implements REQ-capability-plugin-activation-disclosure-v1
+export { composeSemanticClassification, publicCapabilityStamp, } from "./compose-semantic-classifier.js";
+// implements REQ-capability-plugin-activation-disclosure-v1
+export { composeOntologyCatalog, composeOntologyMatches, } from "./compose-ontology-packs.js";
+// implements REQ-capability-plugin-activation-disclosure-v1
+export { SourceAnalysisService, analyzeWithResolution, createConservativeFallbackAnalysis, createSourceAnalysisService, } from "./source-analysis-service.js";
+// implements REQ-capability-plugin-activation-disclosure-v1
+export { EXTERNAL_SEMANTIC_CLASSIFIER_OPERATIONS, allowsExternalSemanticClassifier, } from "./external-allowlist.js";
+// implements REQ-kibi-vocabulary-alignment-capability
+export { composeClaimComparison, composeSubjectRanking, } from "./compose-vocabulary-alignment.js";
+// implements REQ-kibi-vocabulary-alignment-capability
+export { EXTERNAL_VOCABULARY_ALIGNMENT_OPERATIONS, allowsExternalVocabularyAlignment, } from "./external-allowlist.js";

package/dist/plugins/load-plugin.d.ts

@@ -0,0 +1,19 @@
+import { type KibiPluginV1 } from "kibi-plugin-sdk";
+import { type ResolvedProjectPackage } from "./resolve-package.js";
+export type LoadedPlugin = Readonly<{
+    packageName: string;
+    resolved: ResolvedProjectPackage;
+    plugin: KibiPluginV1;
+}>;
+export type LoadPluginOptions = Readonly<{
+    /** Injectable dynamic import for tests. */
+    importModule?: (url: string) => Promise<unknown>;
+    /** Injectable package resolver for tests. */
+    resolvePackage?: (workspaceRoot: string, packageName: string) => ResolvedProjectPackage;
+}>;
+/**
+ * Dynamically import a project-local plugin package and validate the named
+ * `kibiPlugin` export against kibi.plugin.v1.
+ */
+export declare function loadPluginPackage(workspaceRoot: string, packageName: string, options?: LoadPluginOptions): Promise<LoadedPlugin>;
+//# sourceMappingURL=load-plugin.d.ts.map

package/dist/plugins/load-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-plugin.d.ts","sourceRoot":"","sources":["../../src/plugins/load-plugin.ts"],"names":[],"mappings":"AAkBA,OAAO,EACL,KAAK,YAAY,EAGlB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAEL,KAAK,sBAAsB,EAE5B,MAAM,sBAAsB,CAAC;AAG9B,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,sBAAsB,CAAC;IACjC,MAAM,EAAE,YAAY,CAAC;CACtB,CAAC,CAAC;AAGH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,2CAA2C;IAC3C,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACjD,6CAA6C;IAC7C,cAAc,CAAC,EAAE,CACf,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,MAAM,KAChB,sBAAsB,CAAC;CAC7B,CAAC,CAAC;AAMH;;;GAGG;AAEH,wBAAsB,iBAAiB,CACrC,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,YAAY,CAAC,CA8CvB"}

package/dist/plugins/load-plugin.js

@@ -0,0 +1,59 @@
+/*
+ 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 { PluginValidationError, validateKibiPlugin, } from "kibi-plugin-sdk";
+import { PluginResolutionError, resolveProjectLocalPackage, } from "./resolve-package.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Dynamically import a project-local plugin package and validate the named
+ * `kibiPlugin` export against kibi.plugin.v1.
+ */
+// implements REQ-capability-plugin-activation-disclosure-v1, REQ-capability-plugin-observable-behavior-v1
+export async function loadPluginPackage(workspaceRoot, packageName, options = {}) {
+    const resolvePackage = options.resolvePackage ?? resolveProjectLocalPackage;
+    const importModule = options.importModule ?? ((url) => import(url));
+    const resolved = resolvePackage(workspaceRoot, packageName);
+    let moduleExports;
+    try {
+        moduleExports = await importModule(resolved.entryUrl);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new PluginResolutionError("PLUGIN_IMPORT_FAILED", `Failed to import plugin package '${packageName}': ${message}`);
+    }
+    if (!isRecord(moduleExports) || !("kibiPlugin" in moduleExports)) {
+        throw new PluginValidationError("MISSING_KIBI_PLUGIN_EXPORT", `Package '${packageName}' must export a named 'kibiPlugin' binding`);
+    }
+    const plugin = validateKibiPlugin(moduleExports.kibiPlugin);
+    const packageVersion = typeof resolved.packageJson.version === "string"
+        ? resolved.packageJson.version.trim()
+        : "";
+    if (!packageVersion) {
+        throw new PluginValidationError("MISSING_PACKAGE_VERSION", `Package '${packageName}' package.json must declare a version for provider provenance`);
+    }
+    if (plugin.version !== packageVersion) {
+        throw new PluginValidationError("PLUGIN_VERSION_MISMATCH", `Plugin '${plugin.id}' export version '${plugin.version}' does not match resolved package.json version '${packageVersion}'`);
+    }
+    // Host provenance always uses the resolved package manifest version.
+    const stamped = {
+        ...plugin,
+        version: packageVersion,
+    };
+    return { packageName, resolved, plugin: stamped };
+}

package/dist/plugins/project-config.d.ts

@@ -0,0 +1,28 @@
+import { type ProjectKibiConfig } from "kibi-plugin-sdk";
+export type ProjectPackageManifest = Readonly<{
+    name?: string;
+    dependencies?: Readonly<Record<string, string>>;
+    devDependencies?: Readonly<Record<string, string>>;
+    optionalDependencies?: Readonly<Record<string, string>>;
+    peerDependencies?: Readonly<Record<string, string>>;
+    kibi?: unknown;
+}>;
+export declare function readProjectPackageJson(workspaceRoot: string): ProjectPackageManifest;
+/**
+ * Read and validate `package.json#kibi` for capability-plugin activation.
+ * Missing package.json, `kibi`, or `kibi.plugins` yields empty config
+ * (builtin-only), matching historical workspaces without a package manifest.
+ */
+export declare function readProjectKibiConfig(workspaceRoot: string): ProjectKibiConfig;
+export type ConfiguredCapabilityPluginDiagnostic = Readonly<{
+    package: string;
+    capability: string;
+    mode: string;
+    /** True when the package is listed in dependencies, devDependencies, or optionalDependencies. */
+    declared: boolean;
+}>;
+/**
+ * Parsed `package.json#kibi.plugins` rows. Does not import plugin modules.
+ */
+export declare function describeConfiguredCapabilityPlugins(workspaceRoot: string): readonly ConfiguredCapabilityPluginDiagnostic[];
+//# sourceMappingURL=project-config.d.ts.map

package/dist/plugins/project-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-config.d.ts","sourceRoot":"","sources":["../../src/plugins/project-config.ts"],"names":[],"mappings":"AAoBA,OAAO,EAGL,KAAK,iBAAiB,EAEvB,MAAM,iBAAiB,CAAC;AAGzB,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAChD,eAAe,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,oBAAoB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACxD,gBAAgB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB,CAAC,CAAC;AAGH,wBAAgB,sBAAsB,CACpC,aAAa,EAAE,MAAM,GACpB,sBAAsB,CAyBxB;AAED;;;;GAIG;AAEH,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,MAAM,GACpB,iBAAiB,CAOnB;AAED,MAAM,MAAM,oCAAoC,GAAG,QAAQ,CAAC;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,iGAAiG;IACjG,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC,CAAC;AAkBH;;GAEG;AAGH,wBAAgB,mCAAmC,CACjD,aAAa,EAAE,MAAM,GACpB,SAAS,oCAAoC,EAAE,CAsBjD"}

package/dist/plugins/project-config.js

@@ -0,0 +1,90 @@
+/*
+ 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 * as fs from "node:fs";
+import { join } from "node:path";
+import { PluginValidationError, validateProjectKibiConfig, } from "kibi-plugin-sdk";
+// implements REQ-capability-plugin-activation-disclosure-v1
+export function readProjectPackageJson(workspaceRoot) {
+    const packageJsonPath = join(workspaceRoot, "package.json");
+    if (!fs.existsSync(packageJsonPath)) {
+        throw new PluginValidationError("MISSING_PACKAGE_JSON", `No package.json found at ${packageJsonPath}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new PluginValidationError("INVALID_PACKAGE_JSON", `Failed to parse package.json: ${message}`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new PluginValidationError("INVALID_PACKAGE_JSON", "package.json must be a JSON object");
+    }
+    return parsed;
+}
+/**
+ * Read and validate `package.json#kibi` for capability-plugin activation.
+ * Missing package.json, `kibi`, or `kibi.plugins` yields empty config
+ * (builtin-only), matching historical workspaces without a package manifest.
+ */
+// implements REQ-capability-plugin-activation-disclosure-v1, REQ-capability-plugin-observable-behavior-v1
+export function readProjectKibiConfig(workspaceRoot) {
+    const packageJsonPath = join(workspaceRoot, "package.json");
+    if (!fs.existsSync(packageJsonPath)) {
+        return {};
+    }
+    const manifest = readProjectPackageJson(workspaceRoot);
+    return validateProjectKibiConfig(manifest.kibi);
+}
+// implements REQ-capability-plugin-activation-disclosure-v1
+function dependencyDeclared(manifest, packageName) {
+    return [
+        manifest.dependencies,
+        manifest.devDependencies,
+        manifest.optionalDependencies,
+    ].some((dependencies) => Boolean(dependencies) &&
+        Object.prototype.hasOwnProperty.call(dependencies, packageName));
+}
+/**
+ * Parsed `package.json#kibi.plugins` rows. Does not import plugin modules.
+ */
+// implements REQ-capability-plugin-activation-disclosure-v1, REQ-capability-plugin-observable-behavior-v1
+// covered_by TEST-e2e-capability-plugins
+export function describeConfiguredCapabilityPlugins(workspaceRoot) {
+    const config = readProjectKibiConfig(workspaceRoot);
+    const plugins = config.plugins ?? [];
+    if (plugins.length === 0)
+        return [];
+    const manifest = readProjectPackageJson(workspaceRoot);
+    const rows = [];
+    for (const plugin of plugins) {
+        const declared = dependencyDeclared(manifest, plugin.package);
+        for (const capability of Object.keys(plugin.capabilities)) {
+            const entry = plugin.capabilities[capability];
+            if (!entry)
+                continue;
+            rows.push({
+                package: plugin.package,
+                capability,
+                mode: entry.mode,
+                declared,
+            });
+        }
+    }
+    return rows;
+}

package/dist/plugins/registry.d.ts

@@ -0,0 +1,94 @@
+import { type CapabilityId, type KibiPluginV1, type OntologyPackV1, type PluginMode, type PluginPermissions, type PluginProviderStamp, type ProjectKibiConfig, type SemanticClassifierV1, type SymbolExtractorV1, type VocabularyAlignmentV1 } from "kibi-plugin-sdk";
+import { type LoadPluginOptions, loadPluginPackage } from "./load-plugin.js";
+export type BuiltinPluginFactory = () => KibiPluginV1 | Promise<KibiPluginV1>;
+export type CapabilityProviderBinding<T> = Readonly<{
+    pluginId: string;
+    pluginVersion: string;
+    packageName: string | null;
+    mode: PluginMode | "builtin";
+    permissions: PluginPermissions;
+    external: boolean;
+    capability: T;
+    stamp: PluginProviderStamp;
+}>;
+export type CapabilityModeResolution<T> = Readonly<{
+    builtin: CapabilityProviderBinding<T>;
+    /** At most one replace provider for this capability. */
+    replace: CapabilityProviderBinding<T> | null;
+    /** Augment providers in package.json activation order. */
+    augment: readonly CapabilityProviderBinding<T>[];
+    /** Shadow providers never participate in canonical results. */
+    shadow: readonly CapabilityProviderBinding<T>[];
+}>;
+export type CapabilityRegistryOptions = Readonly<{
+    workspaceRoot: string;
+    /** Injected builtin plugin; defaults to a local stub. */
+    builtinFactory?: BuiltinPluginFactory;
+    /** Pre-validated project config; skips package.json when provided. */
+    projectConfig?: ProjectKibiConfig;
+    /** Injectable project-config reader for tests. */
+    readConfig?: (workspaceRoot: string) => ProjectKibiConfig;
+    /** Injectable plugin loader for tests. */
+    loadPlugin?: (workspaceRoot: string, packageName: string, options?: LoadPluginOptions) => Promise<Awaited<ReturnType<typeof loadPluginPackage>>>;
+    loadPluginOptions?: LoadPluginOptions;
+}>;
+/**
+ * Minimal builtin used when no factory is injected and the builtin package is
+ * not yet wired. Satisfies kibi.plugin.v1 validation.
+ */
+export declare function createStubBuiltinPlugin(): KibiPluginV1;
+/**
+ * Per-workspace capability registry. Builtin providers are always present;
+ * configured packages load lazily the first time a capability is resolved.
+ * Not a process-wide singleton — inject or construct per test/runtime.
+ */
+export declare class CapabilityRegistry {
+    readonly workspaceRoot: string;
+    private readonly builtinFactory;
+    private readonly readConfig;
+    private readonly loadPlugin;
+    private readonly loadPluginOptions;
+    private readonly injectedConfig;
+    private builtinPluginPromise;
+    private configPromise;
+    private readonly loadedPackages;
+    private readonly capabilityCache;
+    constructor(options: CapabilityRegistryOptions);
+    getBuiltinPlugin(): Promise<KibiPluginV1>;
+    getProjectConfig(): Promise<ProjectKibiConfig>;
+    resolveSemanticClassifiers(): Promise<CapabilityModeResolution<SemanticClassifierV1>>;
+    resolveOntologyPacks(): Promise<CapabilityModeResolution<OntologyPackV1>>;
+    resolveSymbolExtractors(): Promise<CapabilityModeResolution<SymbolExtractorV1>>;
+    resolveVocabularyAlignment(): Promise<CapabilityModeResolution<VocabularyAlignmentV1>>;
+    resolveCapability(capabilityId: CapabilityId): Promise<CapabilityModeResolution<unknown>>;
+    /**
+     * Canonical providers only (builtin + optional replace + augment).
+     * Shadow bindings are excluded.
+     */
+    canonicalProviders<T>(resolution: CapabilityModeResolution<T>): readonly CapabilityProviderBinding<T>[];
+    private buildCapabilityResolution;
+    private ensurePackageLoaded;
+}
+/**
+ * Explicit cache keyed by workspace root. Injectable — not a hidden global.
+ */
+export declare class CapabilityRegistryCache {
+    private readonly registries;
+    get(workspaceRoot: string): CapabilityRegistry | undefined;
+    getOrCreate(workspaceRoot: string, options?: Omit<CapabilityRegistryOptions, "workspaceRoot">): CapabilityRegistry;
+    set(workspaceRoot: string, registry: CapabilityRegistry): void;
+    clear(): void;
+}
+export declare function createCapabilityRegistry(options: CapabilityRegistryOptions): CapabilityRegistry;
+export declare function createCapabilityRegistryCache(): CapabilityRegistryCache;
+export type EnsureCapabilityRegistryOptions = CapabilityRegistryOptions & {
+    readonly cache?: CapabilityRegistryCache;
+};
+/**
+ * Lazily construct and cache a registry per workspace root.
+ * Callers should supply a cache instance — there is no process-global store.
+ */
+export declare function ensureCapabilityRegistry(workspaceRootOrOptions: string | EnsureCapabilityRegistryOptions, options?: Omit<CapabilityRegistryOptions, "workspaceRoot"> & {
+    readonly cache?: CapabilityRegistryCache;
+}): CapabilityRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/plugins/registry.d.ts.map

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