@agentxm/knowledge-query 0.28.11 → 0.28.13

package/dist/src/corpus/corpus-status.d.ts

@@ -0,0 +1,134 @@
+/**
+ * What the installed Knowledge corpus can answer right now.
+ *
+ * Readiness is a tri-state the caller can act on: `ready` with the corpus
+ * identity and counts, `changing` while sources are still being written, and
+ * `unavailable` with an actionable diagnostic. The report also names the
+ * bundles the unselected scope installs under the same names, so an operator
+ * can tell which corpus a bare command would read.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import { DesiredStateReader, LockfileReader, WorkspaceLocation } from "@agentxm/workspace-state";
+/** Report the discovery contract and the selected corpus's current health. */
+export declare const reportKnowledgeCorpusStatus: () => Effect.Effect<{
+    capabilities: {
+        readonly version: "axm-knowledge-discovery-capabilities-v1";
+        readonly operations: readonly ("status" | "resolve" | "search" | "query" | "get" | "related")[];
+        readonly queryContractVersion: "axm-knowledge-query-v1";
+        readonly strategies: readonly "lexical"[];
+        readonly operators: readonly ("term" | "phrase" | "literal" | "equals" | "not-equals" | "contains")[];
+        readonly tokenizerProfile: {
+            readonly id: "axm-knowledge-lexical-v1";
+            readonly unicodeNormalization: "NFKC";
+            readonly caseNormalization: "unicode-case-fold";
+            readonly termBoundary: "unicode-whitespace-punctuation-camel-code";
+            readonly stemming: false;
+        };
+        readonly searchableFields: readonly ("bundle" | "conceptId" | "title" | "description" | "tag" | "type" | "body" | "resource" | "status" | "staleAfter" | "generated" | "verified" | "trust")[];
+        readonly metadataFilterFields: readonly ("bundle" | "conceptId" | "title" | "description" | "tag" | "type" | "resource" | "kind")[];
+        readonly lifecycleFilterFields: readonly ("status" | "staleAfter" | "generated" | "verified" | "trust")[];
+        readonly extensionProperties: {
+            readonly addressing: "rfc6901-json-pointer";
+            readonly source: "preserved-frontmatter";
+        };
+        readonly limits: {
+            readonly defaultPageSize: number;
+            readonly maximumPageSize: number;
+            readonly defaultPassagesPerResult: number;
+            readonly maximumPassagesPerResult: number;
+            readonly defaultPassageLength: number;
+            readonly maximumPassageLength: number;
+            readonly maximumTraversalDepth: number;
+            readonly maximumFuzzyCandidates: number;
+        };
+        readonly cursor: {
+            readonly mechanism: "stateless-opaque";
+            readonly maximumAgeSeconds: number;
+            readonly binds: readonly ("corpus-fingerprint" | "canonical-query-digest" | "ordering-position")[];
+        };
+        readonly output: {
+            readonly envelope: "axm.machine-output/result-envelope-v1";
+            readonly resultLevel: "concept";
+            readonly paginationKeys: readonly ("cursor" | "items" | "count" | "hasMore")[];
+        };
+    };
+    readiness: "ready";
+    health: {
+        status: "healthy";
+        diagnostics: never[];
+    };
+    corpusFingerprint: string;
+    bundleCount: number;
+    conceptCount: number;
+    scopeCollisions: {
+        checkedScope: "project" | "user";
+        state: "not-determined";
+        bundleNames: never[];
+    } | {
+        checkedScope: "project" | "user";
+        state: "determined";
+        bundleNames: string[];
+    };
+} | {
+    capabilities: {
+        readonly version: "axm-knowledge-discovery-capabilities-v1";
+        readonly operations: readonly ("status" | "resolve" | "search" | "query" | "get" | "related")[];
+        readonly queryContractVersion: "axm-knowledge-query-v1";
+        readonly strategies: readonly "lexical"[];
+        readonly operators: readonly ("term" | "phrase" | "literal" | "equals" | "not-equals" | "contains")[];
+        readonly tokenizerProfile: {
+            readonly id: "axm-knowledge-lexical-v1";
+            readonly unicodeNormalization: "NFKC";
+            readonly caseNormalization: "unicode-case-fold";
+            readonly termBoundary: "unicode-whitespace-punctuation-camel-code";
+            readonly stemming: false;
+        };
+        readonly searchableFields: readonly ("bundle" | "conceptId" | "title" | "description" | "tag" | "type" | "body" | "resource" | "status" | "staleAfter" | "generated" | "verified" | "trust")[];
+        readonly metadataFilterFields: readonly ("bundle" | "conceptId" | "title" | "description" | "tag" | "type" | "resource" | "kind")[];
+        readonly lifecycleFilterFields: readonly ("status" | "staleAfter" | "generated" | "verified" | "trust")[];
+        readonly extensionProperties: {
+            readonly addressing: "rfc6901-json-pointer";
+            readonly source: "preserved-frontmatter";
+        };
+        readonly limits: {
+            readonly defaultPageSize: number;
+            readonly maximumPageSize: number;
+            readonly defaultPassagesPerResult: number;
+            readonly maximumPassagesPerResult: number;
+            readonly defaultPassageLength: number;
+            readonly maximumPassageLength: number;
+            readonly maximumTraversalDepth: number;
+            readonly maximumFuzzyCandidates: number;
+        };
+        readonly cursor: {
+            readonly mechanism: "stateless-opaque";
+            readonly maximumAgeSeconds: number;
+            readonly binds: readonly ("corpus-fingerprint" | "canonical-query-digest" | "ordering-position")[];
+        };
+        readonly output: {
+            readonly envelope: "axm.machine-output/result-envelope-v1";
+            readonly resultLevel: "concept";
+            readonly paginationKeys: readonly ("cursor" | "items" | "count" | "hasMore")[];
+        };
+    };
+    readiness: "changing" | "unavailable";
+    health: {
+        status: "unhealthy";
+        diagnostics: string[];
+    };
+    bundleCount: number;
+    conceptCount: number;
+    scopeCollisions: {
+        checkedScope: "project" | "user";
+        state: "not-determined";
+        bundleNames: never[];
+    } | {
+        checkedScope: "project" | "user";
+        state: "determined";
+        bundleNames: string[];
+    };
+    corpusFingerprint?: never;
+}, 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, import("../knowledge-index.ts").KnowledgeIndex | import("effect/FileSystem").FileSystem | import("effect/Path").Path | DesiredStateReader | WorkspaceLocation | LockfileReader>;
+//# sourceMappingURL=corpus-status.d.ts.map

package/dist/src/corpus/corpus-status.js

@@ -0,0 +1,74 @@
+/**
+ * What the installed Knowledge corpus can answer right now.
+ *
+ * Readiness is a tri-state the caller can act on: `ready` with the corpus
+ * identity and counts, `changing` while sources are still being written, and
+ * `unavailable` with an actionable diagnostic. The report also names the
+ * bundles the unselected scope installs under the same names, so an operator
+ * can tell which corpus a bare command would read.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Result from "effect/Result";
+import { DesiredStateReader, LockfileReader, readOtherScopeState, WorkspaceLocation, } from "@agentxm/workspace-state";
+import { KNOWLEDGE_DISCOVERY_CAPABILITIES } from "../knowledge-capabilities.js";
+import { captureInstalledKnowledgeCorpus } from "./installed-corpus.js";
+/** The Knowledge bundle names this scope has both configured and accepted. */
+const selectedKnowledgeNames = Effect.gen(function* () {
+    const desiredState = yield* DesiredStateReader;
+    const lockfile = yield* LockfileReader;
+    const graph = yield* desiredState.graph();
+    const locked = yield* lockfile.entries("knowledge");
+    return new Set(graph.nodes.flatMap((node) => node.type === "knowledge" && locked[node.name] !== undefined ? [node.name] : []));
+});
+/** Bundle names the unselected scope installs under the same names. */
+const crossScopeCollisions = Effect.gen(function* () {
+    const location = yield* WorkspaceLocation;
+    const fallbackScope = location.scope === "project" ? "user" : "project";
+    const other = yield* readOtherScopeState;
+    if (Option.isNone(other)) {
+        return { checkedScope: fallbackScope, state: "not-determined", bundleNames: [] };
+    }
+    const current = yield* selectedKnowledgeNames;
+    const configured = new Set(Object.keys(other.value.settings.knowledge ?? {}));
+    const locked = new Set(Object.keys(other.value.lockfile.knowledge ?? {}));
+    const bundleNames = [...current]
+        .filter((name) => configured.has(name) && locked.has(name))
+        .sort((left, right) => left.localeCompare(right));
+    return { checkedScope: other.value.scope, state: "determined", bundleNames };
+});
+/** An actionable sentence for whatever stopped the capture. */
+const describeCaptureFailure = (failure) => failure._tag === "KnowledgeCorpusUnavailable" && "detail" in failure
+    ? String(failure.detail)
+    : `The installed Knowledge corpus could not be read (${failure._tag}).`;
+/** Report the discovery contract and the selected corpus's current health. */
+export const reportKnowledgeCorpusStatus = Effect.fn("Knowledge.reportCorpusStatus")(function* () {
+    const capturedResult = yield* Effect.result(captureInstalledKnowledgeCorpus());
+    const scopeCollisions = yield* crossScopeCollisions;
+    if (Result.isSuccess(capturedResult) && capturedResult.success.outcome === "ready") {
+        const captured = capturedResult.success;
+        return {
+            capabilities: KNOWLEDGE_DISCOVERY_CAPABILITIES,
+            readiness: "ready",
+            health: { status: "healthy", diagnostics: [] },
+            corpusFingerprint: captured.snapshot.fingerprint,
+            bundleCount: captured.bundles.length,
+            conceptCount: captured.snapshot.concepts.length,
+            scopeCollisions,
+        };
+    }
+    const diagnostic = Result.isFailure(capturedResult)
+        ? `${describeCaptureFailure(capturedResult.failure)} Correct the source problem and retry.`
+        : "The installed Knowledge corpus kept changing during capture. Retry after updates finish.";
+    return {
+        capabilities: KNOWLEDGE_DISCOVERY_CAPABILITIES,
+        readiness: Result.isFailure(capturedResult) ? "unavailable" : "changing",
+        health: { status: "unhealthy", diagnostics: [diagnostic] },
+        bundleCount: 0,
+        conceptCount: 0,
+        scopeCollisions,
+    };
+});
+//# sourceMappingURL=corpus-status.js.map

package/dist/src/corpus/installed-corpus.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The installed Knowledge corpus every discovery operation reads.
+ *
+ * One entry point: the selected workspace's enabled bundles are read through
+ * the projection's selection fact, captured under a stable double read, and
+ * indexed into one snapshot. Every operation — resolve, search, query, get,
+ * related, status — starts here, so "which corpus did AXM read" has exactly
+ * one answer.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import { type KnowledgeBundleFqn } from "@agentxm/extension-model/unstable/knowledge";
+import { KnowledgeCorpusUnavailable } from "../errors.js";
+import { KnowledgeIndex, type KnowledgeIndexSnapshot } from "../knowledge-index.js";
+/** One captured bundle: its workspace name, published identity, and version. */
+export interface CapturedInstalledBundle {
+    readonly name: string;
+    readonly bundle: KnowledgeBundleFqn;
+    readonly version: string;
+    readonly sourceRoot: string;
+}
+export type InstalledKnowledgeCorpus = {
+    readonly outcome: "ready";
+    readonly snapshot: KnowledgeIndexSnapshot;
+    readonly bundles: ReadonlyArray<CapturedInstalledBundle>;
+} | {
+    readonly outcome: "corpus-changing";
+};
+/**
+ * Capture the enabled installed corpus and build one live, source-backed
+ * index snapshot. A corpus that kept changing under the double read is a
+ * reported outcome, not a failure: the caller retries rather than recovers.
+ */
+export declare const captureInstalledKnowledgeCorpus: (options?: {
+    readonly bundle?: string;
+} | undefined) => Effect.Effect<{
+    outcome: "corpus-changing";
+    snapshot?: never;
+    bundles?: never;
+} | {
+    outcome: "ready";
+    snapshot: KnowledgeIndexSnapshot;
+    bundles: CapturedInstalledBundle[];
+}, 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>;
+//# sourceMappingURL=installed-corpus.d.ts.map

package/dist/src/corpus/installed-corpus.js

@@ -0,0 +1,62 @@
+/**
+ * The installed Knowledge corpus every discovery operation reads.
+ *
+ * One entry point: the selected workspace's enabled bundles are read through
+ * the projection's selection fact, captured under a stable double read, and
+ * indexed into one snapshot. Every operation — resolve, search, query, get,
+ * related, status — starts here, so "which corpus did AXM read" has exactly
+ * one answer.
+ *
+ * @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 { readKnowledgePackageManifest } from "@agentxm/extension-content/knowledge";
+import { KnowledgeBundleFqnSchema, } from "@agentxm/extension-model/unstable/knowledge";
+import { InstalledKnowledgeUnavailable, selectInstalledKnowledgeBundles, } from "@agentxm/workspace-projection";
+import { KnowledgeCorpusUnavailable } from "../errors.js";
+import { captureKnowledgeIndexBundles } from "../knowledge-capture.js";
+import { KnowledgeIndex } from "../knowledge-index.js";
+const isCorpusChanging = (cause) => typeof cause === "object" &&
+    cause !== null &&
+    "_tag" in cause &&
+    cause._tag === "KnowledgeCorpusChangingError";
+/**
+ * Capture the enabled installed corpus and build one live, source-backed
+ * index snapshot. A corpus that kept changing under the double read is a
+ * reported outcome, not a failure: the caller retries rather than recovers.
+ */
+export const captureInstalledKnowledgeCorpus = Effect.fn("Knowledge.captureInstalledCorpus")(function* (options) {
+    const index = yield* KnowledgeIndex;
+    const selected = yield* selectInstalledKnowledgeBundles(options?.bundle === undefined ? undefined : { name: options.bundle }).pipe(Effect.catchTag("InstalledKnowledgeUnavailable", (failure) => Effect.fail(new KnowledgeCorpusUnavailable({
+        reason: failure.reason,
+        detail: failure.detail,
+        ...(failure.bundle === undefined ? {} : { bundle: failure.bundle }),
+    }))));
+    const prepared = yield* Effect.forEach(selected, (entry) => readKnowledgePackageManifest(entry.packageRoot).pipe(Effect.flatMap(({ manifest }) => Schema.decodeUnknownEffect(KnowledgeBundleFqnSchema)(`${manifest.owner}/knowledge/${manifest.name}`).pipe(Effect.map((bundle) => ({
+        name: entry.name,
+        bundle,
+        version: manifest.version,
+        sourceRoot: entry.sourceRoot,
+    })))), Effect.mapError((cause) => new KnowledgeCorpusUnavailable({
+        reason: "source-unreadable",
+        detail: `Failed to read knowledge bundle "${entry.name}" manifest`,
+        bundle: entry.name,
+        cause,
+    }))), { concurrency: 16 });
+    const capturedResult = yield* Effect.result(captureKnowledgeIndexBundles(prepared));
+    if (Result.isFailure(capturedResult)) {
+        if (isCorpusChanging(capturedResult.failure)) {
+            return { outcome: "corpus-changing" };
+        }
+        return yield* new KnowledgeCorpusUnavailable({
+            reason: "source-unreadable",
+            detail: "Failed to capture the installed Knowledge corpus",
+            cause: capturedResult.failure,
+        });
+    }
+    const snapshot = yield* index.makeSnapshot(capturedResult.success);
+    return { outcome: "ready", snapshot, bundles: prepared };
+});
+//# sourceMappingURL=installed-corpus.js.map