@agentxm/knowledge-query 0.28.4-bootstrap.0

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

@@ -0,0 +1,116 @@
+import * as Schema from "effect/Schema";
+import { WORKSPACE_SCOPES } from "@agentxm/extension-model/unstable/workspace-scope";
+export declare const KNOWLEDGE_QUERY_CONTRACT_VERSION = "axm-knowledge-query-v1";
+export declare const KNOWLEDGE_DISCOVERY_OPERATIONS: readonly ["resolve", "search", "query", "get", "related", "status"];
+export declare const KNOWLEDGE_QUERY_OPERATORS: readonly ["term", "phrase", "literal", "equals", "not-equals", "contains"];
+export declare const KNOWLEDGE_SEARCHABLE_FIELDS: readonly ["bundle", "conceptId", "title", "description", "tag", "type", "body", "resource", "status", "staleAfter", "generated", "verified", "trust"];
+export declare const KNOWLEDGE_METADATA_FILTER_FIELDS: readonly ["bundle", "conceptId", "kind", "title", "description", "tag", "type", "resource"];
+export declare const KNOWLEDGE_LIFECYCLE_FILTER_FIELDS: readonly ["status", "staleAfter", "generated", "verified", "trust"];
+export declare const KnowledgeTextClauseSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"term">;
+    readonly value: Schema.NonEmptyString;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"phrase">;
+    readonly value: Schema.NonEmptyString;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"literal">;
+    readonly value: Schema.NonEmptyString;
+}>]>;
+export type KnowledgeTextClause = typeof KnowledgeTextClauseSchema.Type;
+export declare const KnowledgeQueryClauseSchema: Schema.Union<readonly [Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"term">;
+    readonly value: Schema.NonEmptyString;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"phrase">;
+    readonly value: Schema.NonEmptyString;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"literal">;
+    readonly value: Schema.NonEmptyString;
+}>]>, Schema.Struct<{
+    readonly kind: Schema.Literal<"field">;
+    readonly field: Schema.Literals<readonly ["bundle", "conceptId", "title", "description", "tag", "type", "body", "resource", "status", "staleAfter", "generated", "verified", "trust"]>;
+    readonly clause: Schema.Union<readonly [Schema.Struct<{
+        readonly kind: Schema.Literal<"term">;
+        readonly value: Schema.NonEmptyString;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"phrase">;
+        readonly value: Schema.NonEmptyString;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"literal">;
+        readonly value: Schema.NonEmptyString;
+    }>]>;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"metadata">;
+    readonly field: Schema.Literals<readonly ["bundle", "conceptId", "kind", "title", "description", "tag", "type", "resource"]>;
+    readonly operator: Schema.Literals<readonly ["equals", "not-equals", "contains"]>;
+    readonly value: Schema.NonEmptyString;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"lifecycle">;
+    readonly field: Schema.Literals<readonly ["status", "staleAfter", "generated", "verified", "trust"]>;
+    readonly operator: Schema.Literals<readonly ["equals", "not-equals"]>;
+    readonly value: Schema.NonEmptyString;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"property">;
+    readonly pointer: Schema.NonEmptyString;
+    readonly operator: Schema.Literals<readonly ["equals", "not-equals", "contains"]>;
+    readonly value: Schema.NonEmptyString;
+}>]>;
+export type KnowledgeQueryClause = typeof KnowledgeQueryClauseSchema.Type;
+export declare const KnowledgeQuerySchema: Schema.Struct<{
+    readonly version: Schema.Literal<"axm-knowledge-query-v1">;
+    readonly scope: Schema.Literals<readonly ["project", "user"]>;
+    readonly clauses: Schema.$Array<Schema.Union<readonly [Schema.Union<readonly [Schema.Struct<{
+        readonly kind: Schema.Literal<"term">;
+        readonly value: Schema.NonEmptyString;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"phrase">;
+        readonly value: Schema.NonEmptyString;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"literal">;
+        readonly value: Schema.NonEmptyString;
+    }>]>, Schema.Struct<{
+        readonly kind: Schema.Literal<"field">;
+        readonly field: Schema.Literals<readonly ["bundle", "conceptId", "title", "description", "tag", "type", "body", "resource", "status", "staleAfter", "generated", "verified", "trust"]>;
+        readonly clause: Schema.Union<readonly [Schema.Struct<{
+            readonly kind: Schema.Literal<"term">;
+            readonly value: Schema.NonEmptyString;
+        }>, Schema.Struct<{
+            readonly kind: Schema.Literal<"phrase">;
+            readonly value: Schema.NonEmptyString;
+        }>, Schema.Struct<{
+            readonly kind: Schema.Literal<"literal">;
+            readonly value: Schema.NonEmptyString;
+        }>]>;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"metadata">;
+        readonly field: Schema.Literals<readonly ["bundle", "conceptId", "kind", "title", "description", "tag", "type", "resource"]>;
+        readonly operator: Schema.Literals<readonly ["equals", "not-equals", "contains"]>;
+        readonly value: Schema.NonEmptyString;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"lifecycle">;
+        readonly field: Schema.Literals<readonly ["status", "staleAfter", "generated", "verified", "trust"]>;
+        readonly operator: Schema.Literals<readonly ["equals", "not-equals"]>;
+        readonly value: Schema.NonEmptyString;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"property">;
+        readonly pointer: Schema.NonEmptyString;
+        readonly operator: Schema.Literals<readonly ["equals", "not-equals", "contains"]>;
+        readonly value: Schema.NonEmptyString;
+    }>]>>;
+    readonly ordering: Schema.Literals<readonly ["relevance", "metadata"]>;
+    readonly resultLimit: Schema.Number;
+    readonly passageLimit: Schema.Number;
+    readonly passageLength: Schema.Number;
+    readonly cursor: Schema.optional<Schema.NonEmptyString>;
+}>;
+export type KnowledgeQuery = typeof KnowledgeQuerySchema.Type;
+export declare const makeKnowledgeQuery: (scope: (typeof WORKSPACE_SCOPES)[number], clauses: ReadonlyArray<KnowledgeQueryClause>, options?: {
+    readonly ordering?: "relevance" | "metadata";
+    readonly resultLimit?: number;
+    readonly passageLimit?: number;
+    readonly passageLength?: number;
+    readonly cursor?: string;
+}) => KnowledgeQuery;
+/** The cursor and bounds do not change which candidates a canonical query denotes. */
+export declare const knowledgeQueryIdentity: (query: KnowledgeQuery) => unknown;
+//# sourceMappingURL=knowledge-query.d.ts.map

package/dist/src/knowledge-query.js

@@ -0,0 +1,117 @@
+import * as Schema from "effect/Schema";
+import { WORKSPACE_SCOPES } from "@agentxm/extension-model/unstable/workspace-scope";
+export const KNOWLEDGE_QUERY_CONTRACT_VERSION = "axm-knowledge-query-v1";
+export const KNOWLEDGE_DISCOVERY_OPERATIONS = [
+    "resolve",
+    "search",
+    "query",
+    "get",
+    "related",
+    "status",
+];
+export const KNOWLEDGE_QUERY_OPERATORS = [
+    "term",
+    "phrase",
+    "literal",
+    "equals",
+    "not-equals",
+    "contains",
+];
+export const KNOWLEDGE_SEARCHABLE_FIELDS = [
+    "bundle",
+    "conceptId",
+    "title",
+    "description",
+    "tag",
+    "type",
+    "body",
+    "resource",
+    "status",
+    "staleAfter",
+    "generated",
+    "verified",
+    "trust",
+];
+export const KNOWLEDGE_METADATA_FILTER_FIELDS = [
+    "bundle",
+    "conceptId",
+    "kind",
+    "title",
+    "description",
+    "tag",
+    "type",
+    "resource",
+];
+export const KNOWLEDGE_LIFECYCLE_FILTER_FIELDS = [
+    "status",
+    "staleAfter",
+    "generated",
+    "verified",
+    "trust",
+];
+const nonEmptyValue = Schema.NonEmptyString.annotate({
+    description: "A non-empty decoded query value.",
+});
+export const KnowledgeTextClauseSchema = Schema.Union([
+    Schema.Struct({ kind: Schema.Literal("term"), value: nonEmptyValue }),
+    Schema.Struct({ kind: Schema.Literal("phrase"), value: nonEmptyValue }),
+    Schema.Struct({ kind: Schema.Literal("literal"), value: nonEmptyValue }),
+]).annotate({ identifier: "KnowledgeTextClause" });
+export const KnowledgeQueryClauseSchema = Schema.Union([
+    KnowledgeTextClauseSchema,
+    Schema.Struct({
+        kind: Schema.Literal("field"),
+        field: Schema.Literals(KNOWLEDGE_SEARCHABLE_FIELDS),
+        clause: KnowledgeTextClauseSchema,
+    }),
+    Schema.Struct({
+        kind: Schema.Literal("metadata"),
+        field: Schema.Literals(KNOWLEDGE_METADATA_FILTER_FIELDS),
+        operator: Schema.Literals(["equals", "not-equals", "contains"]),
+        value: nonEmptyValue,
+    }),
+    Schema.Struct({
+        kind: Schema.Literal("lifecycle"),
+        field: Schema.Literals(KNOWLEDGE_LIFECYCLE_FILTER_FIELDS),
+        operator: Schema.Literals(["equals", "not-equals"]),
+        value: nonEmptyValue,
+    }),
+    Schema.Struct({
+        kind: Schema.Literal("property"),
+        pointer: Schema.NonEmptyString.check(Schema.makeFilter((value) => value.startsWith("/") ? undefined : "Expected an RFC 6901 JSON Pointer")),
+        operator: Schema.Literals(["equals", "not-equals", "contains"]),
+        value: nonEmptyValue,
+    }),
+]).annotate({ identifier: "KnowledgeQueryClause" });
+export const KnowledgeQuerySchema = Schema.Struct({
+    version: Schema.Literal(KNOWLEDGE_QUERY_CONTRACT_VERSION),
+    scope: Schema.Literals(WORKSPACE_SCOPES),
+    clauses: Schema.Array(KnowledgeQueryClauseSchema),
+    ordering: Schema.Literals(["relevance", "metadata"]),
+    resultLimit: Schema.Number.check(Schema.isInt(), Schema.isBetween({ minimum: 1, maximum: 100 })),
+    passageLimit: Schema.Number.check(Schema.isInt(), Schema.isBetween({ minimum: 0, maximum: 10 })),
+    passageLength: Schema.Number.check(Schema.isInt(), Schema.isBetween({ minimum: 1, maximum: 2_000 })),
+    cursor: Schema.optional(Schema.NonEmptyString),
+}).annotate({
+    identifier: "KnowledgeQuery",
+    title: "Knowledge Query",
+    description: "Canonical, serializable Knowledge discovery query model.",
+});
+export const makeKnowledgeQuery = (scope, clauses, options) => ({
+    version: KNOWLEDGE_QUERY_CONTRACT_VERSION,
+    scope,
+    clauses,
+    ordering: options?.ordering ?? (clauses.length === 0 ? "metadata" : "relevance"),
+    resultLimit: options?.resultLimit ?? 25,
+    passageLimit: options?.passageLimit ?? 3,
+    passageLength: options?.passageLength ?? 500,
+    ...(options?.cursor === undefined ? {} : { cursor: options.cursor }),
+});
+/** The cursor and bounds do not change which candidates a canonical query denotes. */
+export const knowledgeQueryIdentity = (query) => ({
+    version: query.version,
+    scope: query.scope,
+    clauses: query.clauses,
+    ordering: query.ordering,
+});
+//# sourceMappingURL=knowledge-query.js.map

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

@@ -0,0 +1,36 @@
+import * as Effect from "effect/Effect";
+import type { KnowledgeProjectedConcept } from "./knowledge-projection.js";
+import { type KnowledgeRevision } from "@agentxm/extension-model/unstable/knowledge/concept-ref";
+export interface KnowledgeCorpusSource {
+    readonly bundle: string;
+    readonly relativePath: string;
+    /** Filesystem observation metadata is explicitly excluded from the fingerprint. */
+    readonly modifiedAt?: number;
+}
+export interface CapturedKnowledgeSource extends KnowledgeCorpusSource {
+    readonly bytes: Uint8Array;
+    readonly sourceRevision: KnowledgeRevision;
+}
+export interface CapturedKnowledgeCorpus {
+    readonly fingerprint: KnowledgeRevision;
+    readonly sources: ReadonlyArray<CapturedKnowledgeSource>;
+}
+declare const KnowledgeCorpusChangingError_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: "KnowledgeCorpusChangingError";
+} & Readonly<A>;
+export declare class KnowledgeCorpusChangingError extends KnowledgeCorpusChangingError_base<{
+    readonly attempts: number;
+}> {
+}
+export declare const computeKnowledgeSourceRevision: (bytes: Uint8Array) => KnowledgeRevision;
+export declare const computeKnowledgeCorpusFingerprint: (sources: ReadonlyArray<CapturedKnowledgeSource>) => KnowledgeRevision;
+export declare const computeKnowledgeProjectionRevision: (concept: KnowledgeProjectedConcept) => KnowledgeRevision;
+/**
+ * Capture one internally consistent corpus. Every source is read twice; a
+ * changing source retries the complete capture and never yields a mixed view.
+ */
+export declare const captureKnowledgeCorpus: <E>(sources: ReadonlyArray<KnowledgeCorpusSource>, readSource: (source: KnowledgeCorpusSource) => Effect.Effect<Uint8Array, E>, options?: {
+    readonly maxAttempts?: number;
+}) => Effect.Effect<CapturedKnowledgeCorpus, E | KnowledgeCorpusChangingError>;
+export {};
+//# sourceMappingURL=knowledge-revision.d.ts.map

package/dist/src/knowledge-revision.js

@@ -0,0 +1,99 @@
+import { createHash } from "node:crypto";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { KnowledgeRevisionSchema, } from "@agentxm/extension-model/unstable/knowledge/concept-ref";
+export class KnowledgeCorpusChangingError extends Data.TaggedError("KnowledgeCorpusChangingError") {
+}
+const decodeRevision = Schema.decodeUnknownSync(KnowledgeRevisionSchema);
+const revision = (domain, parts) => {
+    const hash = createHash("sha256");
+    const update = (part) => {
+        const bytes = typeof part === "string" ? new TextEncoder().encode(part) : part;
+        hash.update(String(bytes.byteLength));
+        hash.update(":");
+        hash.update(bytes);
+        hash.update(";");
+    };
+    update(domain);
+    for (const part of parts)
+        update(part);
+    return decodeRevision(`sha256:${hash.digest("hex")}`);
+};
+const normalizedRelativePath = (value) => value
+    .replace(/\\/gu, "/")
+    .split("/")
+    .filter((segment) => segment.length > 0 && segment !== ".")
+    .join("/");
+const compareSource = (left, right) => left.bundle.localeCompare(right.bundle) ||
+    normalizedRelativePath(left.relativePath).localeCompare(normalizedRelativePath(right.relativePath));
+export const computeKnowledgeSourceRevision = (bytes) => revision("axm-knowledge-source-revision-v1", [bytes]);
+export const computeKnowledgeCorpusFingerprint = (sources) => {
+    const parts = [];
+    for (const source of [...sources].sort(compareSource)) {
+        parts.push(source.bundle, normalizedRelativePath(source.relativePath), source.bytes);
+    }
+    return revision("axm-knowledge-corpus-fingerprint-v1", parts);
+};
+const canonicalValue = (value, seen = new Map()) => {
+    if (value === null)
+        return "null";
+    switch (typeof value) {
+        case "string":
+            return `string:${value.length}:${value}`;
+        case "number":
+            return `number:${Object.is(value, -0) ? "-0" : String(value)}`;
+        case "boolean":
+            return value ? "boolean:true" : "boolean:false";
+        case "undefined":
+            return "undefined";
+        case "bigint":
+            return `bigint:${String(value)}`;
+        case "object":
+            if (value instanceof Uint8Array) {
+                return `bytes:${value.byteLength}:${Buffer.from(value).toString("base64")}`;
+            }
+            if (seen.has(value))
+                return `reference:${seen.get(value)}`;
+            seen.set(value, seen.size);
+            if (Array.isArray(value)) {
+                return `array:[${value.map((entry) => canonicalValue(entry, seen)).join(",")}]`;
+            }
+            return `object:{${Object.entries(value)
+                .sort(([left], [right]) => left.localeCompare(right))
+                .map(([key, entry]) => `${canonicalValue(key, seen)}=${canonicalValue(entry, seen)}`)
+                .join(",")}}`;
+        default:
+            return `${typeof value}:${String(value)}`;
+    }
+};
+export const computeKnowledgeProjectionRevision = (concept) => revision("axm-knowledge-projection-revision-v1", [canonicalValue(concept)]);
+const equalBytes = (left, right) => left.byteLength === right.byteLength && left.every((byte, index) => right[index] === byte);
+const captureOnce = (sources, readSource) => Effect.forEach([...sources].sort(compareSource), (source) => readSource(source).pipe(Effect.map((bytes) => ({
+    ...source,
+    relativePath: normalizedRelativePath(source.relativePath),
+    bytes,
+    sourceRevision: computeKnowledgeSourceRevision(bytes),
+}))), { concurrency: 16 });
+/**
+ * Capture one internally consistent corpus. Every source is read twice; a
+ * changing source retries the complete capture and never yields a mixed view.
+ */
+export const captureKnowledgeCorpus = (sources, readSource, options) => Effect.gen(function* () {
+    const maxAttempts = Math.max(1, options?.maxAttempts ?? 3);
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        const captured = yield* captureOnce(sources, readSource);
+        const confirmed = yield* captureOnce(sources, readSource);
+        if (captured.length === confirmed.length &&
+            captured.every((source, index) => source.bundle === confirmed[index]?.bundle &&
+                source.relativePath === confirmed[index]?.relativePath &&
+                equalBytes(source.bytes, confirmed[index]?.bytes ?? new Uint8Array()))) {
+            return {
+                fingerprint: computeKnowledgeCorpusFingerprint(captured),
+                sources: captured,
+            };
+        }
+    }
+    return yield* new KnowledgeCorpusChangingError({ attempts: maxAttempts });
+});
+//# sourceMappingURL=knowledge-revision.js.map

package/dist/src/live.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Environment-backed Layers for the knowledge-query feature. Only application
+ * composition imports this module; feature logic keeps the `KnowledgeIndex`
+ * requirement in its Effect environment.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Layer from "effect/Layer";
+import { KnowledgeIndex } from "./knowledge-index.js";
+export declare const KnowledgeIndexLive: Layer.Layer<KnowledgeIndex, never, never>;
+//# sourceMappingURL=live.d.ts.map

package/dist/src/live.js

@@ -0,0 +1,19 @@
+/**
+ * Environment-backed Layers for the knowledge-query feature. Only application
+ * composition imports this module; feature logic keeps the `KnowledgeIndex`
+ * requirement in its Effect environment.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Clock from "effect/Clock";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { KnowledgeIndex, makeKnowledgeIndexSnapshot, queryKnowledgeIndexResult, } from "./knowledge-index.js";
+export const KnowledgeIndexLive = Layer.succeed(KnowledgeIndex, {
+    makeSnapshot: (bundles) => Effect.sync(() => makeKnowledgeIndexSnapshot(bundles)),
+    query: (snapshot, query) => Effect.gen(function* () {
+        const now = yield* Clock.currentTimeMillis;
+        return yield* Effect.fromResult(queryKnowledgeIndexResult(snapshot, query, now));
+    }),
+});
+//# sourceMappingURL=live.js.map

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@agentxm/knowledge-query",
+  "version": "0.28.4-bootstrap.0",
+  "description": "AXM knowledge-query feature: Knowledge concept resolution, retrieval, search, related concepts, and status for the axm CLI. Unstable and unsupported — use the axm.sh CLI.",
+  "type": "module",
+  "license": "FSL-1.1-MIT",
+  "homepage": "https://axm.sh",
+  "bugs": {
+    "url": "https://github.com/agentxm/axm/issues"
+  },
+  "author": "AgentXM <hello@agentxm.ai> (https://agentxm.ai)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentxm/axm.git",
+    "directory": "packages/knowledge-query"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./live": {
+      "types": "./dist/src/live.d.ts",
+      "default": "./dist/src/live.js"
+    }
+  },
+  "files": [
+    "dist/src/",
+    "!**/*.map"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "nx": {
+    "includedScripts": []
+  },
+  "dependencies": {
+    "effect": "4.0.0-rc.112",
+    "@agentxm/extension-model": "^0.28.4-bootstrap.0",
+    "@agentxm/registry-protocol": "^0.28.4-bootstrap.0"
+  },
+  "devDependencies": {
+    "@effect/platform-node": "4.0.0-rc.112",
+    "@effect/vitest": "4.0.0-rc.112",
+    "@types/bun": "^1.3.14",
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "vitest": "^4.1.10"
+  }
+}