@agentxm/knowledge-query 0.28.11 → 0.28.13

package/dist/src/knowledge-discovery.d.ts

@@ -0,0 +1,394 @@
+/**
+ * The read-only application API behind `axm knowledge concepts …`.
+ *
+ * Each operation takes a typed request, captures the selected installed
+ * corpus once, and returns the typed outcome document automation decodes.
+ * Grammar, bounds, conditional-revision semantics, readiness, and the ranking
+ * explanation are decided here; the application maps outcomes onto exit codes
+ * and rendering.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import type { WorkspaceScope } from "@agentxm/extension-model/unstable/workspace-scope";
+import { KnowledgeConceptNotFound, KnowledgeRequestInvalid } from "./errors.js";
+import { KnowledgeIndex } from "./knowledge-index.js";
+import { type KnowledgeQueryRequest, type KnowledgeSearchRequest } from "./query/request.js";
+/** Every discovery operation reports the same two refusals it cannot recover from. */
+export type KnowledgeDiscoveryOutcome<A> = {
+    readonly outcome: "corpus-changing";
+} | {
+    readonly outcome: "cursor-expired";
+} | ({
+    readonly outcome: "ready";
+} & A);
+export declare const KnowledgeDiscovery: {
+    /** Structured query over the installed corpus. */
+    query: (request: KnowledgeQueryRequest & {
+        readonly explain?: boolean;
+    }) => Effect.Effect<{
+        readonly outcome: "corpus-changing";
+        readonly page?: never;
+    } | {
+        readonly outcome: "cursor-expired";
+        readonly page?: never;
+    } | {
+        readonly outcome: "ready";
+        readonly page: {
+            readonly query: {
+                readonly version: "axm-knowledge-query-v1";
+                readonly scope: "project" | "user";
+                readonly clauses: readonly ({
+                    readonly kind: "term";
+                    readonly value: string;
+                } | {
+                    readonly kind: "phrase";
+                    readonly value: string;
+                } | {
+                    readonly kind: "literal";
+                    readonly value: string;
+                } | {
+                    readonly kind: "field";
+                    readonly field: "bundle" | "conceptId" | "title" | "description" | "tag" | "type" | "body" | "resource" | "status" | "staleAfter" | "generated" | "verified" | "trust";
+                    readonly clause: {
+                        readonly kind: "term";
+                        readonly value: string;
+                    } | {
+                        readonly kind: "phrase";
+                        readonly value: string;
+                    } | {
+                        readonly kind: "literal";
+                        readonly value: string;
+                    };
+                } | {
+                    readonly kind: "metadata";
+                    readonly field: "bundle" | "conceptId" | "title" | "description" | "tag" | "type" | "resource" | "kind";
+                    readonly operator: "equals" | "not-equals" | "contains";
+                    readonly value: string;
+                } | {
+                    readonly kind: "lifecycle";
+                    readonly field: "status" | "staleAfter" | "generated" | "verified" | "trust";
+                    readonly operator: "equals" | "not-equals";
+                    readonly value: string;
+                } | {
+                    readonly kind: "property";
+                    readonly pointer: string;
+                    readonly operator: "equals" | "not-equals" | "contains";
+                    readonly value: string;
+                })[];
+                readonly ordering: "metadata" | "relevance";
+                readonly resultLimit: number;
+                readonly passageLimit: number;
+                readonly passageLength: number;
+                readonly cursor?: string | undefined;
+            };
+            readonly items: readonly {
+                readonly kind: "concept" | "index" | "log";
+                readonly relativePath: string;
+                readonly matchedFields: readonly string[];
+                readonly passages: readonly {
+                    readonly text: string;
+                    readonly section: readonly string[];
+                    readonly startLine: number;
+                    readonly endLine: number;
+                    readonly spans: readonly {
+                        readonly clauseIndex: number;
+                        readonly field: string;
+                        readonly start: number;
+                        readonly end: number;
+                    }[];
+                }[];
+                readonly ref: {
+                    readonly bundle: string;
+                    readonly conceptId: string;
+                    readonly bundleVersion: string;
+                    readonly bundleFingerprint: string;
+                    readonly contentRevision: string;
+                };
+                readonly orderingKey: string;
+                readonly title?: string | undefined;
+                readonly description?: string | undefined;
+                readonly status?: string | undefined;
+                readonly staleAfter?: string | undefined;
+                readonly generated?: {
+                    readonly by: string;
+                    readonly at?: string | undefined;
+                } | undefined;
+                readonly verified?: readonly {
+                    readonly by: string;
+                    readonly at?: string | undefined;
+                }[] | undefined;
+                readonly trust?: "unverified" | "machine-confirmed" | "human-reviewed" | undefined;
+            }[];
+            readonly count: number;
+            readonly hasMore: boolean;
+            readonly corpusFingerprint: string;
+            readonly cursor?: string | undefined;
+            readonly explanation?: {
+                readonly strategy: "lexical";
+                readonly ordering: "metadata" | "relevance";
+                readonly rankFactors: readonly {
+                    readonly field: string;
+                    readonly weight: number;
+                }[];
+                readonly tieBreak: string;
+            } | undefined;
+        };
+    }, KnowledgeRequestInvalid | import("./errors.js").KnowledgeCorpusUnavailable | import("@agentxm/workspace-state").SettingsIoError | import("@agentxm/workspace-state").SettingsParseError | import("@agentxm/workspace-state").SettingsDecodeError | import("@agentxm/workspace-state").WorkspaceRootEscape | import("@agentxm/workspace-state").LockfileIoError | import("@agentxm/workspace-state").LockfileParseError | import("@agentxm/workspace-state").LockfileDecodeError | import("@agentxm/workspace-state").LockfileVersionUnsupported, KnowledgeIndex | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@agentxm/workspace-state").DesiredStateReader | import("@agentxm/workspace-state").WorkspaceLocation | import("@agentxm/workspace-state").LockfileReader>;
+    /** Lexical search over the installed corpus. */
+    search: (request: KnowledgeSearchRequest) => Effect.Effect<{
+        readonly outcome: "corpus-changing";
+        readonly page?: never;
+    } | {
+        readonly outcome: "cursor-expired";
+        readonly page?: never;
+    } | {
+        readonly outcome: "ready";
+        readonly page: {
+            readonly query: {
+                readonly version: "axm-knowledge-query-v1";
+                readonly scope: "project" | "user";
+                readonly clauses: readonly ({
+                    readonly kind: "term";
+                    readonly value: string;
+                } | {
+                    readonly kind: "phrase";
+                    readonly value: string;
+                } | {
+                    readonly kind: "literal";
+                    readonly value: string;
+                } | {
+                    readonly kind: "field";
+                    readonly field: "bundle" | "conceptId" | "title" | "description" | "tag" | "type" | "body" | "resource" | "status" | "staleAfter" | "generated" | "verified" | "trust";
+                    readonly clause: {
+                        readonly kind: "term";
+                        readonly value: string;
+                    } | {
+                        readonly kind: "phrase";
+                        readonly value: string;
+                    } | {
+                        readonly kind: "literal";
+                        readonly value: string;
+                    };
+                } | {
+                    readonly kind: "metadata";
+                    readonly field: "bundle" | "conceptId" | "title" | "description" | "tag" | "type" | "resource" | "kind";
+                    readonly operator: "equals" | "not-equals" | "contains";
+                    readonly value: string;
+                } | {
+                    readonly kind: "lifecycle";
+                    readonly field: "status" | "staleAfter" | "generated" | "verified" | "trust";
+                    readonly operator: "equals" | "not-equals";
+                    readonly value: string;
+                } | {
+                    readonly kind: "property";
+                    readonly pointer: string;
+                    readonly operator: "equals" | "not-equals" | "contains";
+                    readonly value: string;
+                })[];
+                readonly ordering: "metadata" | "relevance";
+                readonly resultLimit: number;
+                readonly passageLimit: number;
+                readonly passageLength: number;
+                readonly cursor?: string | undefined;
+            };
+            readonly items: readonly {
+                readonly kind: "concept" | "index" | "log";
+                readonly relativePath: string;
+                readonly matchedFields: readonly string[];
+                readonly passages: readonly {
+                    readonly text: string;
+                    readonly section: readonly string[];
+                    readonly startLine: number;
+                    readonly endLine: number;
+                    readonly spans: readonly {
+                        readonly clauseIndex: number;
+                        readonly field: string;
+                        readonly start: number;
+                        readonly end: number;
+                    }[];
+                }[];
+                readonly ref: {
+                    readonly bundle: string;
+                    readonly conceptId: string;
+                    readonly bundleVersion: string;
+                    readonly bundleFingerprint: string;
+                    readonly contentRevision: string;
+                };
+                readonly orderingKey: string;
+                readonly title?: string | undefined;
+                readonly description?: string | undefined;
+                readonly status?: string | undefined;
+                readonly staleAfter?: string | undefined;
+                readonly generated?: {
+                    readonly by: string;
+                    readonly at?: string | undefined;
+                } | undefined;
+                readonly verified?: readonly {
+                    readonly by: string;
+                    readonly at?: string | undefined;
+                }[] | undefined;
+                readonly trust?: "unverified" | "machine-confirmed" | "human-reviewed" | undefined;
+            }[];
+            readonly count: number;
+            readonly hasMore: boolean;
+            readonly corpusFingerprint: string;
+            readonly cursor?: string | undefined;
+            readonly explanation?: {
+                readonly strategy: "lexical";
+                readonly ordering: "metadata" | "relevance";
+                readonly rankFactors: readonly {
+                    readonly field: string;
+                    readonly weight: number;
+                }[];
+                readonly tieBreak: string;
+            } | undefined;
+        };
+    }, KnowledgeRequestInvalid | import("./errors.js").KnowledgeCorpusUnavailable | import("@agentxm/workspace-state").SettingsIoError | import("@agentxm/workspace-state").SettingsParseError | import("@agentxm/workspace-state").SettingsDecodeError | import("@agentxm/workspace-state").WorkspaceRootEscape | import("@agentxm/workspace-state").LockfileIoError | import("@agentxm/workspace-state").LockfileParseError | import("@agentxm/workspace-state").LockfileDecodeError | import("@agentxm/workspace-state").LockfileVersionUnsupported, KnowledgeIndex | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@agentxm/workspace-state").DesiredStateReader | import("@agentxm/workspace-state").WorkspaceLocation | import("@agentxm/workspace-state").LockfileReader>;
+    /**
+     * One concept by exact identity, optionally conditional on its content
+     * revision. A changed revision is a reported outcome, not a failure: the
+     * caller re-reads at the current revision.
+     */
+    get: (request: {
+        readonly reference: string;
+        readonly ifRevision?: string;
+        readonly raw?: boolean;
+    }) => Effect.Effect<{
+        readonly outcome: "corpus-changing";
+        readonly document?: never;
+    } | {
+        readonly outcome: "revision-changed";
+        readonly document: {
+            outcome: "failed";
+            reason: "revision-changed";
+            ref: {
+                readonly bundle: string;
+                readonly conceptId: string;
+                readonly bundleVersion: string;
+                readonly bundleFingerprint: string;
+                readonly contentRevision: string;
+            };
+            expectedRevision: string;
+            currentRevision: string;
+            concept?: never;
+        };
+    } | {
+        readonly outcome: "ready";
+        readonly document: {
+            outcome: "found";
+            concept: {
+                readonly body: string;
+                readonly kind: "concept" | "index" | "log";
+                readonly relativePath: string;
+                readonly ref: {
+                    readonly bundle: string;
+                    readonly conceptId: string;
+                    readonly bundleVersion: string;
+                    readonly bundleFingerprint: string;
+                    readonly contentRevision: string;
+                };
+                readonly projectionRevision: string;
+                readonly title?: string | undefined;
+                readonly description?: string | undefined;
+                readonly type?: string | undefined;
+                readonly resource?: string | undefined;
+                readonly status?: string | undefined;
+                readonly staleAfter?: string | undefined;
+                readonly generated?: {
+                    readonly by: string;
+                    readonly at?: string | undefined;
+                } | undefined;
+                readonly verified?: readonly {
+                    readonly by: string;
+                    readonly at?: string | undefined;
+                }[] | undefined;
+                readonly trust?: "unverified" | "machine-confirmed" | "human-reviewed" | undefined;
+                readonly tags?: readonly string[] | undefined;
+                readonly frontmatter?: {
+                    readonly [x: string]: unknown;
+                } | undefined;
+                readonly raw?: string | undefined;
+            };
+            reason?: never;
+            ref?: never;
+            expectedRevision?: never;
+            currentRevision?: never;
+        };
+    }, KnowledgeRequestInvalid | import("./errors.js").KnowledgeCorpusUnavailable | KnowledgeConceptNotFound | import("@agentxm/workspace-state").SettingsIoError | import("@agentxm/workspace-state").SettingsParseError | import("@agentxm/workspace-state").SettingsDecodeError | import("@agentxm/workspace-state").WorkspaceRootEscape | import("@agentxm/workspace-state").LockfileIoError | import("@agentxm/workspace-state").LockfileParseError | import("@agentxm/workspace-state").LockfileDecodeError | import("@agentxm/workspace-state").LockfileVersionUnsupported, KnowledgeIndex | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@agentxm/workspace-state").DesiredStateReader | import("@agentxm/workspace-state").WorkspaceLocation | import("@agentxm/workspace-state").LockfileReader>;
+    /**
+     * Resolve a reference to one installed concept. Fuzzy candidate matching is
+     * an explicit request; without it, only an exact reference resolves.
+     */
+    resolve: (request: {
+        readonly input: string;
+        readonly fuzzy?: boolean;
+    }) => Effect.Effect<{
+        readonly outcome: "corpus-changing";
+        readonly document?: never;
+    } | {
+        readonly outcome: "not-found";
+        readonly document: {
+            outcome: "not-found";
+        };
+    } | {
+        readonly outcome: "resolved" | "ambiguous";
+        readonly document: {
+            readonly outcome: "not-found" | "resolved" | "ambiguous";
+            readonly reason?: "ambiguous-reference" | undefined;
+            readonly candidate?: {
+                readonly reason: "exact-reference" | "exact-concept-id" | "exact-title" | "token-match";
+                readonly ref: {
+                    readonly bundle: string;
+                    readonly conceptId: string;
+                    readonly bundleVersion: string;
+                    readonly bundleFingerprint: string;
+                    readonly contentRevision: string;
+                };
+                readonly orderingKey: string;
+                readonly score: number;
+                readonly title?: string | undefined;
+            } | undefined;
+            readonly candidates?: readonly {
+                readonly reason: "exact-reference" | "exact-concept-id" | "exact-title" | "token-match";
+                readonly ref: {
+                    readonly bundle: string;
+                    readonly conceptId: string;
+                    readonly bundleVersion: string;
+                    readonly bundleFingerprint: string;
+                    readonly contentRevision: string;
+                };
+                readonly orderingKey: string;
+                readonly score: number;
+                readonly title?: string | undefined;
+            }[] | undefined;
+        };
+    }, import("./errors.js").KnowledgeCorpusUnavailable | import("@agentxm/workspace-state").SettingsIoError | import("@agentxm/workspace-state").SettingsParseError | import("@agentxm/workspace-state").SettingsDecodeError | import("@agentxm/workspace-state").WorkspaceRootEscape | import("@agentxm/workspace-state").LockfileIoError | import("@agentxm/workspace-state").LockfileParseError | import("@agentxm/workspace-state").LockfileDecodeError | import("@agentxm/workspace-state").LockfileVersionUnsupported, KnowledgeIndex | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@agentxm/workspace-state").DesiredStateReader | import("@agentxm/workspace-state").WorkspaceLocation | import("@agentxm/workspace-state").LockfileReader>;
+    /** Traverse authored links and derived backlinks from one concept. */
+    related: (request: {
+        readonly reference: string;
+        readonly maximumDepth?: number;
+        readonly includeIndexBacklinks?: boolean;
+    }) => Effect.Effect<{
+        readonly outcome: "corpus-changing";
+        readonly document?: never;
+    } | {
+        readonly outcome: "ready";
+        readonly document: {
+            ref: {
+                readonly bundle: string;
+                readonly conceptId: string;
+                readonly bundleVersion: string;
+                readonly bundleFingerprint: string;
+                readonly contentRevision: string;
+            };
+            maximumDepth: number;
+            includesIndexBacklinks: boolean;
+            items: readonly import("./knowledge-graph.js").KnowledgeRelatedConcept[];
+            count: number;
+            corpusFingerprint: string;
+        };
+    }, KnowledgeRequestInvalid | import("./errors.js").KnowledgeCorpusUnavailable | KnowledgeConceptNotFound | import("@agentxm/workspace-state").SettingsIoError | import("@agentxm/workspace-state").SettingsParseError | import("@agentxm/workspace-state").SettingsDecodeError | import("@agentxm/workspace-state").WorkspaceRootEscape | import("@agentxm/workspace-state").LockfileIoError | import("@agentxm/workspace-state").LockfileParseError | import("@agentxm/workspace-state").LockfileDecodeError | import("@agentxm/workspace-state").LockfileVersionUnsupported, KnowledgeIndex | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@agentxm/workspace-state").DesiredStateReader | import("@agentxm/workspace-state").WorkspaceLocation | import("@agentxm/workspace-state").LockfileReader>;
+};
+export type { KnowledgeQueryRequest, KnowledgeSearchRequest, WorkspaceScope };
+//# sourceMappingURL=knowledge-discovery.d.ts.map

package/dist/src/knowledge-discovery.js

@@ -0,0 +1,171 @@
+/**
+ * The read-only application API behind `axm knowledge concepts …`.
+ *
+ * Each operation takes a typed request, captures the selected installed
+ * corpus once, and returns the typed outcome document automation decodes.
+ * Grammar, bounds, conditional-revision semantics, readiness, and the ranking
+ * explanation are decided here; the application maps outcomes onto exit codes
+ * and rendering.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import { KnowledgeRevisionSchema, parseConceptRef, } from "@agentxm/extension-model/unstable/knowledge";
+import { captureInstalledKnowledgeCorpus } from "./corpus/installed-corpus.js";
+import { KnowledgeConceptNotFound, KnowledgeRequestInvalid } from "./errors.js";
+import { KNOWLEDGE_DISCOVERY_CAPABILITIES } from "./knowledge-capabilities.js";
+import { relatedKnowledgeConcepts, resolveKnowledgeConcept } from "./knowledge-graph.js";
+import { getKnowledgeIndexConcept, KnowledgeIndex, } from "./knowledge-index.js";
+import { checkTraversalDepth, explainKnowledgeQuery, makeKnowledgeQueryRequest, makeKnowledgeSearchRequest, } from "./query/request.js";
+const decodeRevision = Schema.decodeUnknownResult(KnowledgeRevisionSchema);
+const conceptDocument = (indexed, raw) => {
+    const source = indexed.source;
+    return {
+        ref: indexed.ref,
+        projectionRevision: indexed.projectionRevision,
+        kind: source.kind,
+        ...(source.authoredTitle === undefined ? {} : { title: source.authoredTitle }),
+        ...(source.type === undefined ? {} : { type: source.type }),
+        ...(source.description === undefined ? {} : { description: source.description }),
+        ...(source.tags === undefined ? {} : { tags: source.tags }),
+        ...(source.resource === undefined ? {} : { resource: source.resource }),
+        ...(source.status === undefined ? {} : { status: source.status }),
+        ...(source.staleAfter === undefined ? {} : { staleAfter: source.staleAfter }),
+        ...(source.generated === undefined ? {} : { generated: source.generated }),
+        ...(source.verified === undefined ? {} : { verified: source.verified }),
+        ...(source.trust === undefined ? {} : { trust: source.trust }),
+        ...(source.frontmatter === undefined ? {} : { frontmatter: source.frontmatter }),
+        relativePath: source.relativePath,
+        body: source.body,
+        ...(raw ? { raw: new TextDecoder().decode(indexed.sourceBytes) } : {}),
+    };
+};
+const runPage = Effect.fn("Knowledge.runPage")(function* (args) {
+    const index = yield* KnowledgeIndex;
+    const captured = yield* captureInstalledKnowledgeCorpus(args.bundle === undefined ? undefined : { bundle: args.bundle });
+    if (captured.outcome === "corpus-changing") {
+        return { outcome: "corpus-changing" };
+    }
+    const pageResult = yield* Effect.result(index.query(captured.snapshot, args.query));
+    if (!Result.isSuccess(pageResult))
+        return { outcome: "cursor-expired" };
+    const page = {
+        query: args.query,
+        corpusFingerprint: captured.snapshot.fingerprint,
+        ...pageResult.success,
+        ...(args.explain ? { explanation: explainKnowledgeQuery(args.query) } : {}),
+    };
+    return { outcome: "ready", page };
+});
+export const KnowledgeDiscovery = {
+    /** Structured query over the installed corpus. */
+    query: Effect.fn("KnowledgeDiscovery.query")(function* (request) {
+        const query = yield* makeKnowledgeQueryRequest(request);
+        return yield* runPage({ query, explain: request.explain === true });
+    }),
+    /** Lexical search over the installed corpus. */
+    search: Effect.fn("KnowledgeDiscovery.search")(function* (request) {
+        const query = yield* makeKnowledgeSearchRequest(request);
+        return yield* runPage({ query, explain: false });
+    }),
+    /**
+     * One concept by exact identity, optionally conditional on its content
+     * revision. A changed revision is a reported outcome, not a failure: the
+     * caller re-reads at the current revision.
+     */
+    get: Effect.fn("KnowledgeDiscovery.get")(function* (request) {
+        const parsed = parseConceptRef(request.reference);
+        if (!Result.isSuccess(parsed)) {
+            return yield* new KnowledgeRequestInvalid({
+                detail: "Expected a concept reference in @owner/knowledge/name#concept-id form",
+            });
+        }
+        const expected = request.ifRevision === undefined ? undefined : decodeRevision(request.ifRevision);
+        if (expected !== undefined && !Result.isSuccess(expected)) {
+            return yield* new KnowledgeRequestInvalid({
+                detail: "--if-revision must be an opaque sha256: revision",
+            });
+        }
+        const captured = yield* captureInstalledKnowledgeCorpus();
+        if (captured.outcome === "corpus-changing")
+            return { outcome: "corpus-changing" };
+        const indexed = getKnowledgeIndexConcept(captured.snapshot, parsed.success.bundle, parsed.success.conceptId);
+        if (indexed === undefined) {
+            return yield* new KnowledgeConceptNotFound({ reference: request.reference });
+        }
+        if (expected !== undefined &&
+            Result.isSuccess(expected) &&
+            expected.success !== indexed.ref.contentRevision) {
+            return {
+                outcome: "revision-changed",
+                document: {
+                    outcome: "failed",
+                    reason: "revision-changed",
+                    ref: indexed.ref,
+                    expectedRevision: expected.success,
+                    currentRevision: indexed.ref.contentRevision,
+                },
+            };
+        }
+        return {
+            outcome: "ready",
+            document: {
+                outcome: "found",
+                concept: conceptDocument(indexed, request.raw === true),
+            },
+        };
+    }),
+    /**
+     * Resolve a reference to one installed concept. Fuzzy candidate matching is
+     * an explicit request; without it, only an exact reference resolves.
+     */
+    resolve: Effect.fn("KnowledgeDiscovery.resolve")(function* (request) {
+        const captured = yield* captureInstalledKnowledgeCorpus();
+        if (captured.outcome === "corpus-changing")
+            return { outcome: "corpus-changing" };
+        const resolved = resolveKnowledgeConcept(captured.snapshot, request.input, KNOWLEDGE_DISCOVERY_CAPABILITIES.limits.maximumFuzzyCandidates, request.fuzzy === true);
+        if (resolved.outcome === "not-found") {
+            return {
+                outcome: "not-found",
+                document: { outcome: "not-found" },
+            };
+        }
+        const document = resolved.outcome === "ambiguous" ? { ...resolved, reason: "ambiguous-reference" } : resolved;
+        return { outcome: resolved.outcome, document };
+    }),
+    /** Traverse authored links and derived backlinks from one concept. */
+    related: Effect.fn("KnowledgeDiscovery.related")(function* (request) {
+        const parsed = parseConceptRef(request.reference);
+        if (!Result.isSuccess(parsed)) {
+            return yield* new KnowledgeRequestInvalid({
+                detail: "Expected a concept reference in @owner/knowledge/name#concept-id form",
+            });
+        }
+        const maximumDepth = yield* checkTraversalDepth(request.maximumDepth ?? 1);
+        const captured = yield* captureInstalledKnowledgeCorpus();
+        if (captured.outcome === "corpus-changing")
+            return { outcome: "corpus-changing" };
+        const root = getKnowledgeIndexConcept(captured.snapshot, parsed.success.bundle, parsed.success.conceptId);
+        if (root === undefined) {
+            return yield* new KnowledgeConceptNotFound({ reference: request.reference });
+        }
+        const includesIndexBacklinks = request.includeIndexBacklinks === true;
+        const items = relatedKnowledgeConcepts(captured.snapshot, parsed.success, maximumDepth, {
+            includeIndexBacklinks: includesIndexBacklinks,
+        });
+        return {
+            outcome: "ready",
+            document: {
+                ref: root.ref,
+                maximumDepth,
+                includesIndexBacklinks,
+                items,
+                count: items.length,
+                corpusFingerprint: captured.snapshot.fingerprint,
+            },
+        };
+    }),
+};
+//# sourceMappingURL=knowledge-discovery.js.map

package/dist/src/knowledge-graph.js

@@ -1,14 +1,15 @@
 import * as Result from "effect/Result";
 import { parseConceptRef, } from "@agentxm/extension-model/unstable/knowledge/concept-ref";
 import { getKnowledgeIndexConcept, } from "./knowledge-index.js";
-import { tokenizeKnowledgeSearchText } from "@agentxm/registry-protocol/unstable/knowledge/knowledge-search";
+import { tokenizeKnowledgeSearchText } from "@agentxm/extension-content/knowledge";
+import { KNOWLEDGE_DISCOVERY_CAPABILITIES } from "./knowledge-capabilities.js";
 const compactKey = (ref) => `${ref.bundle}#${ref.conceptId}`;
 /** Traverse authored outgoing links and derived backlinks with cycle suppression. */
 export const relatedKnowledgeConcepts = (snapshot, start, maximumDepth = 1, options) => {
     const root = getKnowledgeIndexConcept(snapshot, start.bundle, start.conceptId);
     if (root === undefined)
         return [];
-    const depthLimit = Math.max(1, Math.min(3, maximumDepth));
+    const depthLimit = Math.max(1, Math.min(KNOWLEDGE_DISCOVERY_CAPABILITIES.limits.maximumTraversalDepth, maximumDepth));
     const visited = new Set([compactKey(start)]);
     const queue = [{ concept: root, depth: 0 }];
     const results = [];
@@ -88,7 +89,7 @@ const candidate = (concept, reason, score) => ({
     orderingKey: `${concept.ref.bundle}#${concept.ref.conceptId}`,
 });
 /** Resolve an exact concept ref or return a bounded deterministic fuzzy candidate set. */
-export const resolveKnowledgeConcept = (snapshot, input, maximumCandidates = 10, fuzzy = false) => {
+export const resolveKnowledgeConcept = (snapshot, input, maximumCandidates = KNOWLEDGE_DISCOVERY_CAPABILITIES.limits.maximumFuzzyCandidates, fuzzy = false) => {
     const parsed = parseConceptRef(input);
     if (Result.isSuccess(parsed)) {
         const exact = getKnowledgeIndexConcept(snapshot, parsed.success.bundle, parsed.success.conceptId);
@@ -116,7 +117,7 @@ export const resolveKnowledgeConcept = (snapshot, input, maximumCandidates = 10,
         return [];
     })
         .sort((left, right) => right.score - left.score || left.orderingKey.localeCompare(right.orderingKey))
-        .slice(0, Math.max(1, Math.min(10, maximumCandidates)));
+        .slice(0, Math.max(1, maximumCandidates));
     if (candidates.length === 0)
         return { outcome: "not-found", candidates: [] };
     if (candidates.length === 1) {

package/dist/src/knowledge-index.d.ts

@@ -5,7 +5,7 @@ import { type KnowledgeBundleFqn, type KnowledgeRevision, type ResolvedConceptRe
 import { type KnowledgeBodyPassage, type KnowledgeProjectedConcept, type KnowledgeSearchableField } from "./knowledge-projection.js";
 import { type KnowledgeQuery } from "./knowledge-query.js";
 import { type CapturedKnowledgeSource } from "./knowledge-revision.js";
-import type { KnowledgeConcept, KnowledgeInspection } from "@agentxm/registry-protocol/unstable/knowledge/okf";
+import type { KnowledgeConcept, KnowledgeInspection } from "@agentxm/extension-content/knowledge";
 export interface KnowledgeIndexBundleInput {
     readonly bundle: KnowledgeBundleFqn;
     readonly version: string;
@@ -62,6 +62,19 @@ export declare class KnowledgeCursorInvalidError extends KnowledgeCursorInvalidE
 }> {
 }
 export declare const makeKnowledgeIndexSnapshot: (bundles: ReadonlyArray<KnowledgeIndexBundleInput>) => KnowledgeIndexSnapshot;
+/** One ranking factor of the lexical strategy, derived from the same weights the ranker uses. */
+export interface KnowledgeRankFactor {
+    readonly field: string;
+    readonly weight: number;
+}
+/**
+ * The published ranking explanation: the fields the lexical strategy weights,
+ * highest first, and the catch-all weight every other field carries. Derived
+ * from `fieldWeight`, so an explanation can never drift from the ranking.
+ */
+export declare const KNOWLEDGE_RANK_FACTORS: ReadonlyArray<KnowledgeRankFactor>;
+/** How the lexical strategy orders results that rank equally. */
+export declare const KNOWLEDGE_RANK_TIE_BREAK = "bundle FQN, then concept ID";
 export declare const queryKnowledgeIndexResult: (snapshot: KnowledgeIndexSnapshot, query: KnowledgeQuery, now: number) => Result.Result<KnowledgeQueryPage, KnowledgeCursorInvalidError>;
 export declare const queryKnowledgeIndex: (snapshot: KnowledgeIndexSnapshot, query: KnowledgeQuery, now: number) => KnowledgeQueryPage;
 export declare const getKnowledgeIndexConcept: (snapshot: KnowledgeIndexSnapshot, bundle: string, conceptId: string) => KnowledgeIndexedConcept | undefined;

package/dist/src/knowledge-index.js

@@ -8,7 +8,7 @@ import { resolveKnowledgeFrontmatterPointer } from "./knowledge-projection.js";
 import { projectKnowledgeConcepts, } from "./knowledge-projection.js";
 import { knowledgeQueryIdentity, } from "./knowledge-query.js";
 import { computeKnowledgeCorpusFingerprint, computeKnowledgeProjectionRevision, } from "./knowledge-revision.js";
-import { tokenizeKnowledgeSearchText } from "@agentxm/registry-protocol/unstable/knowledge/knowledge-search";
+import { tokenizeKnowledgeSearchText } from "@agentxm/extension-content/knowledge";
 export class KnowledgeCursorInvalidError extends Data.TaggedError("KnowledgeCursorInvalidError") {
 }
 const CURSOR_VERSION = "axm-knowledge-cursor-v1";
@@ -219,6 +219,20 @@ const fieldWeight = (field) => {
             return 1;
     }
 };
+/**
+ * The published ranking explanation: the fields the lexical strategy weights,
+ * highest first, and the catch-all weight every other field carries. Derived
+ * from `fieldWeight`, so an explanation can never drift from the ranking.
+ */
+export const KNOWLEDGE_RANK_FACTORS = [
+    ...["title", "conceptId", "tag", "description", "type", "body"].map((field) => ({
+        field,
+        weight: fieldWeight(field),
+    })),
+    { field: "other", weight: fieldWeight("bundle") },
+];
+/** How the lexical strategy orders results that rank equally. */
+export const KNOWLEDGE_RANK_TIE_BREAK = "bundle FQN, then concept ID";
 const locateTokenSequence = (text, tokens) => {
     if (tokens.length === 0)
         return undefined;