@agentxm/knowledge-query 0.28.4-bootstrap.0

package/LICENSE

@@ -0,0 +1,110 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2025-2026 AgentXM, Inc.
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/src/index.d.ts

@@ -0,0 +1,8 @@
+export { relatedKnowledgeConcepts, resolveKnowledgeConcept, type KnowledgeRelatedConcept, type KnowledgeRelation, type KnowledgeResolveCandidate, type KnowledgeResolveResult, } from "./knowledge-graph.js";
+export { projectKnowledgeConcepts, resolveKnowledgeFrontmatterPointer, type KnowledgeBacklink, type KnowledgeBodyPassage, type KnowledgeFrontmatterPointerResult, type KnowledgeOutgoingLink, type KnowledgeProjectedConcept, type KnowledgeSearchableField, type KnowledgeSearchableUnit, } from "./knowledge-projection.js";
+export { captureKnowledgeCorpus, computeKnowledgeCorpusFingerprint, computeKnowledgeProjectionRevision, computeKnowledgeSourceRevision, KnowledgeCorpusChangingError, type CapturedKnowledgeCorpus, type CapturedKnowledgeSource, type KnowledgeCorpusSource, } from "./knowledge-revision.js";
+export { KNOWLEDGE_DISCOVERY_CAPABILITIES, KNOWLEDGE_DISCOVERY_CAPABILITIES_VERSION, KnowledgeDiscoveryCapabilitiesSchema, type KnowledgeDiscoveryCapabilities, } from "./knowledge-capabilities.js";
+export { knowledgeQueryIdentity, KnowledgeQueryClauseSchema, KnowledgeQuerySchema, KnowledgeTextClauseSchema, makeKnowledgeQuery, KNOWLEDGE_DISCOVERY_OPERATIONS, KNOWLEDGE_LIFECYCLE_FILTER_FIELDS, KNOWLEDGE_METADATA_FILTER_FIELDS, KNOWLEDGE_QUERY_CONTRACT_VERSION, KNOWLEDGE_QUERY_OPERATORS, KNOWLEDGE_SEARCHABLE_FIELDS, type KnowledgeQuery, type KnowledgeQueryClause, type KnowledgeTextClause, } from "./knowledge-query.js";
+export { getKnowledgeIndexConcept, KnowledgeCursorInvalidError, KnowledgeIndex, makeKnowledgeIndexSnapshot, queryKnowledgeIndex, queryKnowledgeIndexResult, type KnowledgeConceptResult, type KnowledgeCursorInvalidReason, type KnowledgeIndexBundleInput, type KnowledgeIndexedConcept, type KnowledgeIndexService, type KnowledgeIndexSnapshot, type KnowledgeMatchSpan, type KnowledgeQueryPage, type KnowledgeResultPassage, } from "./knowledge-index.js";
+export { captureKnowledgeIndexBundles, KnowledgeCapturedSourceMissingError, type KnowledgeBundleCaptureDescriptor, } from "./knowledge-capture.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.js

@@ -0,0 +1,8 @@
+export { relatedKnowledgeConcepts, resolveKnowledgeConcept, } from "./knowledge-graph.js";
+export { projectKnowledgeConcepts, resolveKnowledgeFrontmatterPointer, } from "./knowledge-projection.js";
+export { captureKnowledgeCorpus, computeKnowledgeCorpusFingerprint, computeKnowledgeProjectionRevision, computeKnowledgeSourceRevision, KnowledgeCorpusChangingError, } from "./knowledge-revision.js";
+export { KNOWLEDGE_DISCOVERY_CAPABILITIES, KNOWLEDGE_DISCOVERY_CAPABILITIES_VERSION, KnowledgeDiscoveryCapabilitiesSchema, } from "./knowledge-capabilities.js";
+export { knowledgeQueryIdentity, KnowledgeQueryClauseSchema, KnowledgeQuerySchema, KnowledgeTextClauseSchema, makeKnowledgeQuery, KNOWLEDGE_DISCOVERY_OPERATIONS, KNOWLEDGE_LIFECYCLE_FILTER_FIELDS, KNOWLEDGE_METADATA_FILTER_FIELDS, KNOWLEDGE_QUERY_CONTRACT_VERSION, KNOWLEDGE_QUERY_OPERATORS, KNOWLEDGE_SEARCHABLE_FIELDS, } from "./knowledge-query.js";
+export { getKnowledgeIndexConcept, KnowledgeCursorInvalidError, KnowledgeIndex, makeKnowledgeIndexSnapshot, queryKnowledgeIndex, queryKnowledgeIndexResult, } from "./knowledge-index.js";
+export { captureKnowledgeIndexBundles, KnowledgeCapturedSourceMissingError, } from "./knowledge-capture.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,46 @@
+import * as Schema from "effect/Schema";
+export declare const KNOWLEDGE_DISCOVERY_CAPABILITIES_VERSION = "axm-knowledge-discovery-capabilities-v1";
+export declare const KnowledgeDiscoveryCapabilitiesSchema: Schema.Struct<{
+    readonly version: Schema.Literal<"axm-knowledge-discovery-capabilities-v1">;
+    readonly operations: Schema.$Array<Schema.Literals<readonly ["resolve", "search", "query", "get", "related", "status"]>>;
+    readonly queryContractVersion: Schema.Literal<"axm-knowledge-query-v1">;
+    readonly strategies: Schema.$Array<Schema.Literal<"lexical">>;
+    readonly operators: Schema.$Array<Schema.Literals<readonly ["term", "phrase", "literal", "equals", "not-equals", "contains"]>>;
+    readonly tokenizerProfile: Schema.Struct<{
+        readonly id: Schema.Literal<"axm-knowledge-lexical-v1">;
+        readonly unicodeNormalization: Schema.Literal<"NFKC">;
+        readonly caseNormalization: Schema.Literal<"unicode-case-fold">;
+        readonly termBoundary: Schema.Literal<"unicode-whitespace-punctuation-camel-code">;
+        readonly stemming: Schema.Literal<false>;
+    }>;
+    readonly searchableFields: Schema.$Array<Schema.Literals<readonly ["bundle", "conceptId", "title", "description", "tag", "type", "body", "resource", "status", "staleAfter", "generated", "verified", "trust"]>>;
+    readonly metadataFilterFields: Schema.$Array<Schema.Literals<readonly ["bundle", "conceptId", "kind", "title", "description", "tag", "type", "resource"]>>;
+    readonly lifecycleFilterFields: Schema.$Array<Schema.Literals<readonly ["status", "staleAfter", "generated", "verified", "trust"]>>;
+    readonly extensionProperties: Schema.Struct<{
+        readonly addressing: Schema.Literal<"rfc6901-json-pointer">;
+        readonly source: Schema.Literal<"preserved-frontmatter">;
+    }>;
+    readonly limits: Schema.Struct<{
+        readonly defaultPageSize: Schema.Number;
+        readonly maximumPageSize: Schema.Number;
+        readonly defaultPassagesPerResult: Schema.Number;
+        readonly maximumPassagesPerResult: Schema.Number;
+        readonly defaultPassageLength: Schema.Number;
+        readonly maximumPassageLength: Schema.Number;
+        readonly maximumTraversalDepth: Schema.Number;
+        readonly maximumFuzzyCandidates: Schema.Number;
+    }>;
+    readonly cursor: Schema.Struct<{
+        readonly mechanism: Schema.Literal<"stateless-opaque">;
+        readonly maximumAgeSeconds: Schema.Number;
+        readonly binds: Schema.$Array<Schema.Literals<readonly ["corpus-fingerprint", "canonical-query-digest", "ordering-position"]>>;
+    }>;
+    readonly output: Schema.Struct<{
+        readonly envelope: Schema.Literal<"axm.machine-output/result-envelope-v1">;
+        readonly resultLevel: Schema.Literal<"concept">;
+        readonly paginationKeys: Schema.$Array<Schema.Literals<readonly ["items", "count", "hasMore", "cursor"]>>;
+    }>;
+}>;
+export type KnowledgeDiscoveryCapabilities = typeof KnowledgeDiscoveryCapabilitiesSchema.Type;
+export declare const KNOWLEDGE_DISCOVERY_CAPABILITIES: KnowledgeDiscoveryCapabilities;
+//# sourceMappingURL=knowledge-capabilities.d.ts.map

package/dist/src/knowledge-capabilities.js

@@ -0,0 +1,84 @@
+import * as Schema from "effect/Schema";
+import { KNOWLEDGE_SEARCH_TOKENIZER_PROFILE } from "@agentxm/registry-protocol/unstable/knowledge/knowledge-search";
+import { KNOWLEDGE_DISCOVERY_OPERATIONS, KNOWLEDGE_LIFECYCLE_FILTER_FIELDS, KNOWLEDGE_METADATA_FILTER_FIELDS, KNOWLEDGE_QUERY_CONTRACT_VERSION, KNOWLEDGE_QUERY_OPERATORS, KNOWLEDGE_SEARCHABLE_FIELDS, } from "./knowledge-query.js";
+export const KNOWLEDGE_DISCOVERY_CAPABILITIES_VERSION = "axm-knowledge-discovery-capabilities-v1";
+export const KnowledgeDiscoveryCapabilitiesSchema = Schema.Struct({
+    version: Schema.Literal(KNOWLEDGE_DISCOVERY_CAPABILITIES_VERSION),
+    operations: Schema.Array(Schema.Literals(KNOWLEDGE_DISCOVERY_OPERATIONS)),
+    queryContractVersion: Schema.Literal(KNOWLEDGE_QUERY_CONTRACT_VERSION),
+    strategies: Schema.Array(Schema.Literal("lexical")),
+    operators: Schema.Array(Schema.Literals(KNOWLEDGE_QUERY_OPERATORS)),
+    tokenizerProfile: Schema.Struct({
+        id: Schema.Literal(KNOWLEDGE_SEARCH_TOKENIZER_PROFILE.id),
+        unicodeNormalization: Schema.Literal(KNOWLEDGE_SEARCH_TOKENIZER_PROFILE.unicodeNormalization),
+        caseNormalization: Schema.Literal(KNOWLEDGE_SEARCH_TOKENIZER_PROFILE.caseNormalization),
+        termBoundary: Schema.Literal(KNOWLEDGE_SEARCH_TOKENIZER_PROFILE.termBoundary),
+        stemming: Schema.Literal(KNOWLEDGE_SEARCH_TOKENIZER_PROFILE.stemming),
+    }),
+    searchableFields: Schema.Array(Schema.Literals(KNOWLEDGE_SEARCHABLE_FIELDS)),
+    metadataFilterFields: Schema.Array(Schema.Literals(KNOWLEDGE_METADATA_FILTER_FIELDS)),
+    lifecycleFilterFields: Schema.Array(Schema.Literals(KNOWLEDGE_LIFECYCLE_FILTER_FIELDS)),
+    extensionProperties: Schema.Struct({
+        addressing: Schema.Literal("rfc6901-json-pointer"),
+        source: Schema.Literal("preserved-frontmatter"),
+    }),
+    limits: Schema.Struct({
+        defaultPageSize: Schema.Number,
+        maximumPageSize: Schema.Number,
+        defaultPassagesPerResult: Schema.Number,
+        maximumPassagesPerResult: Schema.Number,
+        defaultPassageLength: Schema.Number,
+        maximumPassageLength: Schema.Number,
+        maximumTraversalDepth: Schema.Number,
+        maximumFuzzyCandidates: Schema.Number,
+    }),
+    cursor: Schema.Struct({
+        mechanism: Schema.Literal("stateless-opaque"),
+        maximumAgeSeconds: Schema.Number,
+        binds: Schema.Array(Schema.Literals(["corpus-fingerprint", "canonical-query-digest", "ordering-position"])),
+    }),
+    output: Schema.Struct({
+        envelope: Schema.Literal("axm.machine-output/result-envelope-v1"),
+        resultLevel: Schema.Literal("concept"),
+        paginationKeys: Schema.Array(Schema.Literals(["items", "count", "hasMore", "cursor"])),
+    }),
+}).annotate({
+    identifier: "KnowledgeDiscoveryCapabilities",
+    title: "Knowledge Discovery Capabilities",
+});
+export const KNOWLEDGE_DISCOVERY_CAPABILITIES = {
+    version: KNOWLEDGE_DISCOVERY_CAPABILITIES_VERSION,
+    operations: KNOWLEDGE_DISCOVERY_OPERATIONS,
+    queryContractVersion: KNOWLEDGE_QUERY_CONTRACT_VERSION,
+    strategies: ["lexical"],
+    operators: KNOWLEDGE_QUERY_OPERATORS,
+    tokenizerProfile: KNOWLEDGE_SEARCH_TOKENIZER_PROFILE,
+    searchableFields: KNOWLEDGE_SEARCHABLE_FIELDS,
+    metadataFilterFields: KNOWLEDGE_METADATA_FILTER_FIELDS,
+    lifecycleFilterFields: KNOWLEDGE_LIFECYCLE_FILTER_FIELDS,
+    extensionProperties: {
+        addressing: "rfc6901-json-pointer",
+        source: "preserved-frontmatter",
+    },
+    limits: {
+        defaultPageSize: 25,
+        maximumPageSize: 100,
+        defaultPassagesPerResult: 3,
+        maximumPassagesPerResult: 10,
+        defaultPassageLength: 500,
+        maximumPassageLength: 2_000,
+        maximumTraversalDepth: 3,
+        maximumFuzzyCandidates: 10,
+    },
+    cursor: {
+        mechanism: "stateless-opaque",
+        maximumAgeSeconds: 86_400,
+        binds: ["corpus-fingerprint", "canonical-query-digest", "ordering-position"],
+    },
+    output: {
+        envelope: "axm.machine-output/result-envelope-v1",
+        resultLevel: "concept",
+        paginationKeys: ["items", "count", "hasMore", "cursor"],
+    },
+};
+//# sourceMappingURL=knowledge-capabilities.js.map

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

@@ -0,0 +1,28 @@
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import type { KnowledgeBundleFqn } from "@agentxm/extension-model/unstable/knowledge/concept-ref";
+import type { KnowledgeIndexBundleInput } from "./knowledge-index.js";
+import { type KnowledgeCorpusChangingError } from "./knowledge-revision.js";
+export interface KnowledgeBundleCaptureDescriptor {
+    readonly bundle: KnowledgeBundleFqn;
+    readonly version: string;
+    readonly sourceRoot: string;
+}
+declare const KnowledgeCapturedSourceMissingError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "KnowledgeCapturedSourceMissingError";
+} & Readonly<A>;
+export declare class KnowledgeCapturedSourceMissingError extends KnowledgeCapturedSourceMissingError_base<{
+    readonly bundle: string;
+    readonly relativePath: string;
+}> {
+}
+/**
+ * Capture and parse all selected bundles from the same double-read corpus view.
+ * Absolute roots are used only for I/O and never enter revisions or results.
+ */
+export declare const captureKnowledgeIndexBundles: (descriptors: ReadonlyArray<KnowledgeBundleCaptureDescriptor>, options?: {
+    readonly maxAttempts?: number;
+}) => Effect.Effect<ReadonlyArray<KnowledgeIndexBundleInput>, unknown | KnowledgeCorpusChangingError | KnowledgeCapturedSourceMissingError, FileSystem.FileSystem | Path.Path>;
+export {};
+//# sourceMappingURL=knowledge-capture.d.ts.map

package/dist/src/knowledge-capture.js

@@ -0,0 +1,49 @@
+// @effect-diagnostics anyUnknownInErrorContext:off — corpus readers deliberately preserve caller-owned foreign read errors
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import { captureKnowledgeCorpus, } from "./knowledge-revision.js";
+import { collectKnowledgeBundleEntries, inspectKnowledgeEntries, } from "@agentxm/registry-protocol/unstable/knowledge/okf";
+export class KnowledgeCapturedSourceMissingError extends Data.TaggedError("KnowledgeCapturedSourceMissingError") {
+}
+const sourceKey = (bundle, relativePath) => `${bundle.length}:${bundle}${relativePath.length}:${relativePath}`;
+/**
+ * Capture and parse all selected bundles from the same double-read corpus view.
+ * Absolute roots are used only for I/O and never enter revisions or results.
+ */
+export const captureKnowledgeIndexBundles = (descriptors, options) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const prepared = yield* Effect.forEach([...descriptors].sort((left, right) => left.bundle.localeCompare(right.bundle)), (descriptor) => collectKnowledgeBundleEntries(descriptor.sourceRoot).pipe(Effect.map((entries) => ({ ...descriptor, entries }))), { concurrency: 16 });
+    const roots = new Map(prepared.map((descriptor) => [descriptor.bundle, descriptor.sourceRoot]));
+    const corpusSources = prepared.flatMap((descriptor) => descriptor.entries
+        .filter((entry) => entry.type === "File")
+        .map((entry) => ({ bundle: descriptor.bundle, relativePath: entry.relativePath })));
+    const readSource = (source) => {
+        const root = roots.get(source.bundle);
+        return root === undefined
+            ? Effect.fail(new KnowledgeCapturedSourceMissingError({
+                bundle: source.bundle,
+                relativePath: source.relativePath,
+            }))
+            : fs.readFile(path.join(root, source.relativePath));
+    };
+    const captured = yield* captureKnowledgeCorpus(corpusSources, readSource, options);
+    const byPath = new Map(captured.sources.map((source) => [sourceKey(source.bundle, source.relativePath), source]));
+    return yield* Effect.forEach(prepared, (descriptor) => inspectKnowledgeEntries(descriptor.entries, (relativePath) => {
+        const source = byPath.get(sourceKey(descriptor.bundle, relativePath));
+        return source === undefined
+            ? Effect.fail(new KnowledgeCapturedSourceMissingError({
+                bundle: descriptor.bundle,
+                relativePath,
+            }))
+            : Effect.succeed(new TextDecoder().decode(source.bytes));
+    }).pipe(Effect.map((inspection) => ({
+        bundle: descriptor.bundle,
+        version: descriptor.version,
+        inspection,
+        sources: captured.sources.filter((source) => source.bundle === descriptor.bundle),
+    }))), { concurrency: 16 });
+});
+//# sourceMappingURL=knowledge-capture.js.map

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

@@ -0,0 +1,40 @@
+import { type ConceptRef, type ResolvedConceptRef } from "@agentxm/extension-model/unstable/knowledge/concept-ref";
+import { type KnowledgeIndexSnapshot } from "./knowledge-index.js";
+export type KnowledgeRelation = "outgoing" | "backlink";
+export interface KnowledgeRelatedConcept {
+    readonly ref: ResolvedConceptRef;
+    readonly title?: string;
+    readonly relation: KnowledgeRelation;
+    readonly depth: number;
+    readonly via: ConceptRef;
+    readonly evidence: {
+        readonly source: ConceptRef;
+        readonly sourceRelativePath: string;
+        readonly line: number;
+    };
+    readonly orderingKey: string;
+}
+/** Traverse authored outgoing links and derived backlinks with cycle suppression. */
+export declare const relatedKnowledgeConcepts: (snapshot: KnowledgeIndexSnapshot, start: ConceptRef, maximumDepth?: number, options?: {
+    readonly includeIndexBacklinks?: boolean;
+}) => ReadonlyArray<KnowledgeRelatedConcept>;
+export interface KnowledgeResolveCandidate {
+    readonly ref: ResolvedConceptRef;
+    readonly title?: string;
+    readonly reason: "exact-reference" | "exact-concept-id" | "exact-title" | "token-match";
+    readonly score: number;
+    readonly orderingKey: string;
+}
+export type KnowledgeResolveResult = {
+    readonly outcome: "resolved";
+    readonly candidate: KnowledgeResolveCandidate;
+} | {
+    readonly outcome: "ambiguous";
+    readonly candidates: ReadonlyArray<KnowledgeResolveCandidate>;
+} | {
+    readonly outcome: "not-found";
+    readonly candidates: ReadonlyArray<never>;
+};
+/** Resolve an exact concept ref or return a bounded deterministic fuzzy candidate set. */
+export declare const resolveKnowledgeConcept: (snapshot: KnowledgeIndexSnapshot, input: string, maximumCandidates?: number, fuzzy?: boolean) => KnowledgeResolveResult;
+//# sourceMappingURL=knowledge-graph.d.ts.map

package/dist/src/knowledge-graph.js

@@ -0,0 +1,130 @@
+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";
+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 visited = new Set([compactKey(start)]);
+    const queue = [{ concept: root, depth: 0 }];
+    const results = [];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (current === undefined || current.depth >= depthLimit)
+            continue;
+        const neighbors = [
+            ...current.concept.projected.outgoingLinks.flatMap((link) => link.resolvedConceptId === undefined
+                ? []
+                : [
+                    {
+                        relation: "outgoing",
+                        conceptId: link.resolvedConceptId,
+                        evidence: {
+                            source: {
+                                bundle: current.concept.ref.bundle,
+                                conceptId: current.concept.ref.conceptId,
+                            },
+                            sourceRelativePath: current.concept.projected.relativePath,
+                            line: link.line,
+                        },
+                    },
+                ]),
+            ...current.concept.projected.backlinks.flatMap((link) => {
+                const source = getKnowledgeIndexConcept(snapshot, current.concept.ref.bundle, link.sourceConceptId);
+                if (source === undefined)
+                    return [];
+                if (source.projected.kind === "index" && options?.includeIndexBacklinks !== true)
+                    return [];
+                return [
+                    {
+                        relation: "backlink",
+                        conceptId: link.sourceConceptId,
+                        evidence: {
+                            source: { bundle: source.ref.bundle, conceptId: source.ref.conceptId },
+                            sourceRelativePath: link.sourceRelativePath,
+                            line: link.line,
+                        },
+                    },
+                ];
+            }),
+        ].sort((left, right) => left.conceptId.localeCompare(right.conceptId) ||
+            left.relation.localeCompare(right.relation));
+        for (const neighbor of neighbors) {
+            const indexed = getKnowledgeIndexConcept(snapshot, current.concept.ref.bundle, neighbor.conceptId);
+            if (indexed === undefined)
+                continue;
+            const key = compactKey(indexed.ref);
+            if (visited.has(key))
+                continue;
+            visited.add(key);
+            const depth = current.depth + 1;
+            results.push({
+                ref: indexed.ref,
+                ...(indexed.projected.title === undefined ? {} : { title: indexed.projected.title }),
+                relation: neighbor.relation,
+                depth,
+                via: {
+                    bundle: current.concept.ref.bundle,
+                    conceptId: current.concept.ref.conceptId,
+                },
+                evidence: neighbor.evidence,
+                orderingKey: `${String(depth).padStart(2, "0")}:${key}:${neighbor.relation}`,
+            });
+            queue.push({ concept: indexed, depth });
+        }
+    }
+    return results.sort((left, right) => left.orderingKey.localeCompare(right.orderingKey));
+};
+const normalized = (value) => value.normalize("NFKC").toUpperCase().toLowerCase();
+const candidate = (concept, reason, score) => ({
+    ref: concept.ref,
+    ...(concept.projected.title === undefined ? {} : { title: concept.projected.title }),
+    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) => {
+    const parsed = parseConceptRef(input);
+    if (Result.isSuccess(parsed)) {
+        const exact = getKnowledgeIndexConcept(snapshot, parsed.success.bundle, parsed.success.conceptId);
+        return exact === undefined
+            ? { outcome: "not-found", candidates: [] }
+            : { outcome: "resolved", candidate: candidate(exact, "exact-reference", 100) };
+    }
+    if (!fuzzy)
+        return { outcome: "not-found", candidates: [] };
+    const expected = normalized(input);
+    const queryTokens = tokenizeKnowledgeSearchText(input);
+    const candidates = snapshot.concepts
+        .flatMap((concept) => {
+        if (normalized(concept.ref.conceptId) === expected) {
+            return [candidate(concept, "exact-concept-id", 80)];
+        }
+        if (concept.projected.title !== undefined &&
+            normalized(concept.projected.title) === expected) {
+            return [candidate(concept, "exact-title", 60)];
+        }
+        const candidateTokens = tokenizeKnowledgeSearchText(`${concept.ref.conceptId} ${concept.projected.title ?? ""}`);
+        if (queryTokens.length > 0 && queryTokens.every((token) => candidateTokens.includes(token))) {
+            return [candidate(concept, "token-match", 20 + queryTokens.length)];
+        }
+        return [];
+    })
+        .sort((left, right) => right.score - left.score || left.orderingKey.localeCompare(right.orderingKey))
+        .slice(0, Math.max(1, Math.min(10, maximumCandidates)));
+    if (candidates.length === 0)
+        return { outcome: "not-found", candidates: [] };
+    if (candidates.length === 1) {
+        const first = candidates[0];
+        return first === undefined
+            ? { outcome: "not-found", candidates: [] }
+            : { outcome: "resolved", candidate: first };
+    }
+    return { outcome: "ambiguous", candidates };
+};
+//# sourceMappingURL=knowledge-graph.js.map

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

@@ -0,0 +1,76 @@
+import * as Effect from "effect/Effect";
+import * as Result from "effect/Result";
+import * as ServiceMap from "effect/Context";
+import { type KnowledgeBundleFqn, type KnowledgeRevision, type ResolvedConceptRef } from "@agentxm/extension-model/unstable/knowledge/concept-ref";
+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";
+export interface KnowledgeIndexBundleInput {
+    readonly bundle: KnowledgeBundleFqn;
+    readonly version: string;
+    readonly inspection: KnowledgeInspection;
+    readonly sources: ReadonlyArray<CapturedKnowledgeSource>;
+}
+export interface KnowledgeIndexedConcept {
+    readonly ref: ResolvedConceptRef;
+    readonly projectionRevision: KnowledgeRevision;
+    readonly projected: KnowledgeProjectedConcept;
+    readonly source: KnowledgeConcept;
+    readonly sourceBytes: Uint8Array;
+}
+export interface KnowledgeIndexSnapshot {
+    readonly fingerprint: KnowledgeRevision;
+    readonly concepts: ReadonlyArray<KnowledgeIndexedConcept>;
+}
+export interface KnowledgeMatchSpan {
+    readonly clauseIndex: number;
+    readonly field: KnowledgeSearchableField;
+    readonly start: number;
+    readonly end: number;
+}
+export interface KnowledgeResultPassage extends KnowledgeBodyPassage {
+    readonly spans: ReadonlyArray<KnowledgeMatchSpan>;
+}
+export interface KnowledgeConceptResult {
+    readonly ref: ResolvedConceptRef;
+    readonly orderingKey: string;
+    readonly matchedFields: ReadonlyArray<KnowledgeSearchableField>;
+    readonly passages: ReadonlyArray<KnowledgeResultPassage>;
+    readonly kind: KnowledgeProjectedConcept["kind"];
+    readonly title?: string;
+    readonly description?: string;
+    readonly status?: string;
+    readonly staleAfter?: string;
+    readonly generated?: KnowledgeProjectedConcept["generated"];
+    readonly verified?: KnowledgeProjectedConcept["verified"];
+    readonly trust?: KnowledgeProjectedConcept["trust"];
+    readonly relativePath: string;
+}
+export interface KnowledgeQueryPage {
+    readonly items: ReadonlyArray<KnowledgeConceptResult>;
+    readonly count: number;
+    readonly hasMore: boolean;
+    readonly cursor?: string;
+}
+export type KnowledgeCursorInvalidReason = "invalid" | "expired" | "corpus-changed" | "query-changed";
+declare const KnowledgeCursorInvalidError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "KnowledgeCursorInvalidError";
+} & Readonly<A>;
+export declare class KnowledgeCursorInvalidError extends KnowledgeCursorInvalidError_base<{
+    readonly reason: KnowledgeCursorInvalidReason;
+}> {
+}
+export declare const makeKnowledgeIndexSnapshot: (bundles: ReadonlyArray<KnowledgeIndexBundleInput>) => KnowledgeIndexSnapshot;
+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;
+export interface KnowledgeIndexService {
+    readonly makeSnapshot: (bundles: ReadonlyArray<KnowledgeIndexBundleInput>) => Effect.Effect<KnowledgeIndexSnapshot>;
+    readonly query: (snapshot: KnowledgeIndexSnapshot, query: KnowledgeQuery) => Effect.Effect<KnowledgeQueryPage, KnowledgeCursorInvalidError>;
+}
+declare const KnowledgeIndex_base: ServiceMap.ServiceClass<KnowledgeIndex, "@agentxm/knowledge-query/knowledge-index/KnowledgeIndex", KnowledgeIndexService>;
+export declare class KnowledgeIndex extends KnowledgeIndex_base {
+}
+export {};
+//# sourceMappingURL=knowledge-index.d.ts.map