@agentxm/knowledge-query 0.28.11 → 0.28.13

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

@@ -1,4 +1,4 @@
-import type { KnowledgeActorRecord, KnowledgeAuthoredLink, KnowledgeConcept, KnowledgeDocumentKind, KnowledgeTrustTier } from "@agentxm/registry-protocol/unstable/knowledge/okf";
+import type { KnowledgeActorRecord, KnowledgeAuthoredLink, KnowledgeConcept, KnowledgeDocumentKind, KnowledgeTrustTier } from "@agentxm/extension-content/knowledge";
 export type KnowledgeSearchableField = "bundle" | "conceptId" | "title" | "description" | "tag" | "type" | "body" | "resource" | "status" | "staleAfter" | "generated" | "verified" | "trust";
 export interface KnowledgeBodyPassage {
     readonly text: string;

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

@@ -0,0 +1,47 @@
+/**
+ * Validate Open Knowledge Format bundles without changing them.
+ *
+ * The caller selects either the installed corpus (all bundles, or one by
+ * name) or a locally authored package directory — never both. The verdict is
+ * a typed report: every diagnostic located by bundle and path, and validity
+ * decided by whether any diagnostic is an error.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Path from "effect/Path";
+import { WorkspaceLocation } from "@agentxm/workspace-state";
+import type { KnowledgeLintQueryResult } from "../documents.js";
+import { KnowledgeCorpusUnavailable, KnowledgeRequestInvalid } from "../errors.js";
+export interface LintKnowledgeRequest {
+    /** One installed bundle by name; omit for every installed bundle. */
+    readonly bundle?: string;
+    /** A locally authored Knowledge package directory, relative to the workspace. */
+    readonly packagePath?: string;
+}
+export interface LintKnowledgeResult {
+    readonly document: KnowledgeLintQueryResult;
+    /** How many bundles were validated, for the success sentence. */
+    readonly bundleCount: number;
+    /** Diagnostics of error severity; a non-empty list means the verdict is invalid. */
+    readonly errorCount: number;
+}
+/** Validate the selected installed bundles, or one authored package. */
+export declare const lintKnowledge: (request: LintKnowledgeRequest) => Effect.Effect<{
+    document: {
+        valid: boolean;
+        diagnostics: {
+            code: import("@agentxm/extension-content/knowledge").KnowledgeDiagnosticCode;
+            severity: "error" | "warning";
+            relativePath: string;
+            line?: number;
+            column?: number;
+            message: string;
+            details?: import("@agentxm/extension-content/knowledge").KnowledgeFrontmatterParseDetails;
+            bundle: string;
+        }[];
+    };
+    bundleCount: number;
+    errorCount: number;
+}, KnowledgeRequestInvalid | 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, import("effect/FileSystem").FileSystem | Path.Path | import("@agentxm/workspace-state").DesiredStateReader | WorkspaceLocation | import("@agentxm/workspace-state").LockfileReader>;
+//# sourceMappingURL=lint-knowledge.d.ts.map

package/dist/src/lint/lint-knowledge.js

@@ -0,0 +1,61 @@
+// @effect-diagnostics anyUnknownInErrorContext:off — lint accepts opaque OKF accessor errors only at its diagnostic boundary
+/**
+ * Validate Open Knowledge Format bundles without changing them.
+ *
+ * The caller selects either the installed corpus (all bundles, or one by
+ * name) or a locally authored package directory — never both. The verdict is
+ * a typed report: every diagnostic located by bundle and path, and validity
+ * decided by whether any diagnostic is an error.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Path from "effect/Path";
+import { inspectKnowledgePackage, } from "@agentxm/extension-content/knowledge";
+import { InstalledKnowledgeUnavailable, selectInstalledKnowledgeBundles, } from "@agentxm/workspace-projection";
+import { WorkspaceLocation } from "@agentxm/workspace-state";
+import { KnowledgeCorpusUnavailable, KnowledgeRequestInvalid } from "../errors.js";
+/** One installed or authored bundle's diagnostics, tagged with its bundle name. */
+const flatten = (bundles) => bundles.flatMap(({ name, inspection }) => inspection.diagnostics.map((item) => ({ bundle: name, ...item })));
+const inspectAuthored = Effect.fn("Knowledge.lintAuthored")(function* (packagePath) {
+    const location = yield* WorkspaceLocation;
+    const path = yield* Path.Path;
+    const inspected = yield* inspectKnowledgePackage(path.resolve(location.baseDir, packagePath)).pipe(Effect.mapError((cause) => new KnowledgeCorpusUnavailable({
+        reason: "source-unreadable",
+        detail: `Failed to inspect authored Knowledge package ${packagePath}`,
+        cause,
+    })));
+    return [inspected];
+});
+const inspectInstalled = Effect.fn("Knowledge.lintInstalled")(function* (bundle) {
+    const selected = yield* selectInstalledKnowledgeBundles(bundle === undefined ? undefined : { name: bundle }).pipe(Effect.catchTag("InstalledKnowledgeUnavailable", (failure) => Effect.fail(new KnowledgeCorpusUnavailable({
+        reason: failure.reason,
+        detail: failure.detail,
+        ...(failure.bundle === undefined ? {} : { bundle: failure.bundle }),
+    }))));
+    return yield* Effect.forEach(selected, (entry) => inspectKnowledgePackage(entry.packageRoot).pipe(Effect.map((inspected) => ({ ...inspected, name: entry.name })), Effect.mapError((cause) => new KnowledgeCorpusUnavailable({
+        reason: "source-unreadable",
+        detail: `Failed to inspect knowledge bundle "${entry.name}"`,
+        bundle: entry.name,
+        cause,
+    }))), { concurrency: "unbounded" });
+});
+/** Validate the selected installed bundles, or one authored package. */
+export const lintKnowledge = Effect.fn("Knowledge.lint")(function* (request) {
+    if (request.bundle !== undefined && request.packagePath !== undefined) {
+        return yield* new KnowledgeRequestInvalid({
+            detail: "Choose either an installed bundle name or --path, not both",
+        });
+    }
+    const bundles = request.packagePath === undefined
+        ? yield* inspectInstalled(request.bundle)
+        : yield* inspectAuthored(request.packagePath);
+    const diagnostics = flatten(bundles);
+    const errorCount = diagnostics.filter((diagnostic) => diagnostic.severity === "error").length;
+    return {
+        document: { valid: errorCount === 0, diagnostics },
+        bundleCount: bundles.length,
+        errorCount,
+    };
+});
+//# sourceMappingURL=lint-knowledge.js.map

package/dist/src/query/request.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The published Knowledge discovery request grammar and its bounds.
+ *
+ * Callers hand over the filter expressions a person typed; this module decides
+ * what they mean, refuses what the published contract does not admit, and
+ * builds the canonical query. The grammar (`=`, `!=`, `~=`, JSON-pointer
+ * properties, searchable field names) and every numeric bound live here, keyed
+ * to the same capabilities document discovery publishes.
+ *
+ * @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 { KnowledgeRequestInvalid } from "../errors.js";
+import { type KnowledgeQuery } from "../knowledge-query.js";
+/** The filter expressions one structured query request carries. */
+export interface KnowledgeQueryRequest {
+    readonly scope: WorkspaceScope;
+    readonly expression?: string;
+    readonly fields?: ReadonlyArray<string>;
+    readonly properties?: ReadonlyArray<string>;
+    readonly metadata?: ReadonlyArray<string>;
+    readonly lifecycle?: ReadonlyArray<string>;
+    readonly tags?: ReadonlyArray<string>;
+    readonly bundle?: string;
+    readonly kind?: "concept" | "index" | "log";
+    readonly status?: string;
+    readonly resultLimit?: number;
+    readonly passageLimit?: number;
+    readonly passageLength?: number;
+    readonly cursor?: string;
+}
+/** A lexical search request: one text expression plus paging. */
+export interface KnowledgeSearchRequest {
+    readonly scope: WorkspaceScope;
+    readonly expression: string;
+    readonly resultLimit?: number;
+    readonly cursor?: string;
+}
+/** The published explanation of how the lexical strategy ranked a page. */
+export interface KnowledgeQueryExplanation {
+    readonly strategy: "lexical";
+    readonly ordering: "relevance" | "metadata";
+    readonly rankFactors: ReadonlyArray<{
+        readonly field: string;
+        readonly weight: number;
+    }>;
+    readonly tieBreak: string;
+}
+/** Explain a query's ranking from the ranker's own weights. */
+export declare const explainKnowledgeQuery: (query: KnowledgeQuery) => KnowledgeQueryExplanation;
+/** Build the canonical query one structured request denotes. */
+export declare const makeKnowledgeQueryRequest: (request: KnowledgeQueryRequest) => Effect.Effect<KnowledgeQuery, KnowledgeRequestInvalid>;
+/** Build the canonical query one lexical search request denotes. */
+export declare const makeKnowledgeSearchRequest: (request: KnowledgeSearchRequest) => Effect.Effect<KnowledgeQuery, KnowledgeRequestInvalid>;
+/** Refuse a traversal depth outside the published maximum. */
+export declare const checkTraversalDepth: (depth: number) => Effect.Effect<number, KnowledgeRequestInvalid>;
+//# sourceMappingURL=request.d.ts.map

package/dist/src/query/request.js

@@ -0,0 +1,242 @@
+/**
+ * The published Knowledge discovery request grammar and its bounds.
+ *
+ * Callers hand over the filter expressions a person typed; this module decides
+ * what they mean, refuses what the published contract does not admit, and
+ * builds the canonical query. The grammar (`=`, `!=`, `~=`, JSON-pointer
+ * properties, searchable field names) and every numeric bound live here, keyed
+ * to the same capabilities document discovery publishes.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import { parseKnowledgeSearchQuery } from "@agentxm/extension-content/knowledge";
+import { KNOWLEDGE_DISCOVERY_CAPABILITIES } from "../knowledge-capabilities.js";
+import { KNOWLEDGE_RANK_FACTORS, KNOWLEDGE_RANK_TIE_BREAK } from "../knowledge-index.js";
+import { KnowledgeRequestInvalid } from "../errors.js";
+import { KNOWLEDGE_LIFECYCLE_FILTER_FIELDS, KNOWLEDGE_METADATA_FILTER_FIELDS, KNOWLEDGE_SEARCHABLE_FIELDS, makeKnowledgeQuery, } from "../knowledge-query.js";
+const limits = KNOWLEDGE_DISCOVERY_CAPABILITIES.limits;
+/** Explain a query's ranking from the ranker's own weights. */
+export const explainKnowledgeQuery = (query) => ({
+    strategy: "lexical",
+    ordering: query.ordering,
+    rankFactors: KNOWLEDGE_RANK_FACTORS,
+    tieBreak: KNOWLEDGE_RANK_TIE_BREAK,
+});
+const textClauses = (input) => {
+    const parsed = parseKnowledgeSearchQuery(input);
+    if (!parsed.ok)
+        return parsed.detail;
+    return parsed.query.clauses.map((clause) => {
+        switch (clause.kind) {
+            case "term":
+                return { kind: "term", value: clause.token };
+            case "phrase":
+                return { kind: "phrase", value: clause.tokens.join(" ") };
+            case "literal":
+                return { kind: "literal", value: clause.value };
+            default:
+                return clause;
+        }
+    });
+};
+const splitAssignment = (input) => {
+    const separator = input.indexOf("=");
+    if (separator <= 0 || separator === input.length - 1)
+        return undefined;
+    return [input.slice(0, separator), input.slice(separator + 1)];
+};
+const splitFilterAssignment = (input) => {
+    for (const [token, operator] of [
+        ["!=", "not-equals"],
+        ["~=", "contains"],
+        ["=", "equals"],
+    ]) {
+        const separator = input.indexOf(token);
+        if (separator <= 0 || separator + token.length === input.length)
+            continue;
+        return [input.slice(0, separator), operator, input.slice(separator + token.length)];
+    }
+    return undefined;
+};
+const fieldClauses = (inputs) => {
+    const clauses = [];
+    for (const input of inputs) {
+        const assignment = splitAssignment(input);
+        if (assignment === undefined)
+            return `Expected --field FIELD=QUERY, received "${input}"`;
+        const [fieldName, query] = assignment;
+        const field = KNOWLEDGE_SEARCHABLE_FIELDS.find((candidate) => candidate === fieldName);
+        if (field === undefined)
+            return `Unknown searchable field "${fieldName}"`;
+        const parsed = textClauses(query);
+        if (typeof parsed === "string")
+            return parsed;
+        for (const clause of parsed) {
+            if (clause.kind !== "term" && clause.kind !== "phrase" && clause.kind !== "literal") {
+                continue;
+            }
+            clauses.push({ kind: "field", field, clause });
+        }
+    }
+    return clauses;
+};
+const propertyClauses = (inputs) => {
+    const clauses = [];
+    for (const input of inputs) {
+        const assignment = splitFilterAssignment(input);
+        if (assignment === undefined ||
+            !assignment[0].startsWith("/") ||
+            /~(?:[^01]|$)/u.test(assignment[0])) {
+            return `Expected --property /json/pointer{=|!=|~=}VALUE, received "${input}"`;
+        }
+        clauses.push({
+            kind: "property",
+            pointer: assignment[0],
+            operator: assignment[1],
+            value: assignment[2],
+        });
+    }
+    return clauses;
+};
+const metadataClauses = (inputs) => {
+    const clauses = [];
+    for (const input of inputs) {
+        const assignment = splitFilterAssignment(input);
+        if (assignment === undefined) {
+            return `Expected --metadata FIELD{=|!=|~=}VALUE, received "${input}"`;
+        }
+        const [fieldName, operator, value] = assignment;
+        const field = KNOWLEDGE_METADATA_FILTER_FIELDS.find((candidate) => candidate === fieldName);
+        if (field === undefined)
+            return `Unknown metadata field "${fieldName}"`;
+        clauses.push({ kind: "metadata", field, operator, value });
+    }
+    return clauses;
+};
+const lifecycleClauses = (inputs) => {
+    const clauses = [];
+    for (const input of inputs) {
+        const assignment = splitFilterAssignment(input);
+        if (assignment === undefined) {
+            return `Expected --lifecycle FIELD{=|!=}VALUE, received "${input}"`;
+        }
+        const [fieldName, operator, value] = assignment;
+        const field = KNOWLEDGE_LIFECYCLE_FILTER_FIELDS.find((candidate) => candidate === fieldName);
+        if (field === undefined)
+            return `Unknown lifecycle field "${fieldName}"`;
+        if (operator === "contains")
+            return "Lifecycle filters do not support the contains operator";
+        clauses.push({ kind: "lifecycle", field, operator, value });
+    }
+    return clauses;
+};
+const buildClauses = (request) => {
+    const base = request.expression === undefined ? [] : textClauses(request.expression);
+    if (typeof base === "string")
+        return base;
+    const fields = fieldClauses(request.fields ?? []);
+    if (typeof fields === "string")
+        return fields;
+    const properties = propertyClauses(request.properties ?? []);
+    if (typeof properties === "string")
+        return properties;
+    const metadata = metadataClauses(request.metadata ?? []);
+    if (typeof metadata === "string")
+        return metadata;
+    const lifecycle = lifecycleClauses(request.lifecycle ?? []);
+    if (typeof lifecycle === "string")
+        return lifecycle;
+    const tags = request.tags ?? [];
+    if (tags.some((value) => value.length === 0) || request.bundle === "" || request.status === "") {
+        return "Filter values must not be empty";
+    }
+    return [
+        ...base,
+        ...fields,
+        ...properties,
+        ...metadata,
+        ...lifecycle,
+        ...tags.map((value) => ({
+            kind: "metadata",
+            field: "tag",
+            operator: "equals",
+            value,
+        })),
+        ...(request.bundle === undefined
+            ? []
+            : [
+                {
+                    kind: "metadata",
+                    field: "bundle",
+                    operator: "equals",
+                    value: request.bundle,
+                },
+            ]),
+        ...(request.kind === undefined
+            ? []
+            : [
+                {
+                    kind: "metadata",
+                    field: "kind",
+                    operator: "equals",
+                    value: request.kind,
+                },
+            ]),
+        ...(request.status === undefined
+            ? []
+            : [
+                {
+                    kind: "lifecycle",
+                    field: "status",
+                    operator: "equals",
+                    value: request.status,
+                },
+            ]),
+    ];
+};
+const withinBound = (value, minimum, maximum) => value === undefined || (Number.isSafeInteger(value) && value >= minimum && value <= maximum);
+const paging = (request) => ({
+    ...(request.resultLimit === undefined ? {} : { resultLimit: request.resultLimit }),
+    ...(request.passageLimit === undefined ? {} : { passageLimit: request.passageLimit }),
+    ...(request.passageLength === undefined ? {} : { passageLength: request.passageLength }),
+    ...(request.cursor === undefined ? {} : { cursor: request.cursor }),
+});
+/**
+ * Refuse a request whose paging bounds fall outside what discovery publishes.
+ * Whole numbers only: a fractional bound is not a page size discovery can honour.
+ */
+const checkPagingBounds = (request) => withinBound(request.resultLimit, 1, limits.maximumPageSize) &&
+    withinBound(request.passageLimit, 0, limits.maximumPassagesPerResult) &&
+    withinBound(request.passageLength, 1, limits.maximumPassageLength)
+    ? undefined
+    : `Query bounds must keep --limit within 1-${limits.maximumPageSize}, --passages within 0-${limits.maximumPassagesPerResult}, and --passage-length within 1-${limits.maximumPassageLength}`;
+/** Build the canonical query one structured request denotes. */
+export const makeKnowledgeQueryRequest = (request) => {
+    const clauses = buildClauses(request);
+    if (typeof clauses === "string") {
+        return Effect.fail(new KnowledgeRequestInvalid({ detail: clauses }));
+    }
+    const bounds = checkPagingBounds(request);
+    if (bounds !== undefined)
+        return Effect.fail(new KnowledgeRequestInvalid({ detail: bounds }));
+    return Effect.succeed(makeKnowledgeQuery(request.scope, clauses, paging(request)));
+};
+/** Build the canonical query one lexical search request denotes. */
+export const makeKnowledgeSearchRequest = (request) => {
+    const clauses = textClauses(request.expression);
+    if (typeof clauses === "string") {
+        return Effect.fail(new KnowledgeRequestInvalid({ detail: clauses }));
+    }
+    const bounds = checkPagingBounds(request);
+    if (bounds !== undefined)
+        return Effect.fail(new KnowledgeRequestInvalid({ detail: bounds }));
+    return Effect.succeed(makeKnowledgeQuery(request.scope, clauses, paging(request)));
+};
+/** Refuse a traversal depth outside the published maximum. */
+export const checkTraversalDepth = (depth) => Number.isSafeInteger(depth) && depth >= 1 && depth <= limits.maximumTraversalDepth
+    ? Effect.succeed(depth)
+    : Effect.fail(new KnowledgeRequestInvalid({
+        detail: `Depth must be between 1 and ${limits.maximumTraversalDepth}`,
+    }));
+//# sourceMappingURL=request.js.map

package/dist/src/testing.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @agentxm/knowledge-query deterministic fixtures and ports.
+ *
+ * A throwaway workspace with authored Knowledge bundles, the layer discovery
+ * needs over it, and the changing-source port that proves capture refuses an
+ * unstable corpus. Production source never imports this module.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import type { WorkspaceScope } from "@agentxm/extension-model/unstable/workspace-scope";
+export declare const knowledgeBundleFqn = "@acme/knowledge/platform";
+/** An OKF concept document with fixture frontmatter and the given body. */
+export declare const knowledgeDocument: (body: string, frontmatter?: Readonly<Record<string, unknown>>) => string;
+export interface KnowledgeFixtureBundle {
+    readonly name: string;
+    readonly enabled?: boolean;
+    readonly instructionEntry?: boolean;
+    readonly documents?: Readonly<Record<string, string>>;
+}
+/**
+ * A project workspace whose Knowledge bundles are authored in place, exactly
+ * as `axm knowledge new` leaves them.
+ */
+export declare const makeKnowledgeFixtureWorkspace: (options?: {
+    readonly bundles?: ReadonlyArray<KnowledgeFixtureBundle>;
+    readonly scope?: WorkspaceScope;
+}) => {
+    root: string;
+    sourcePath: (bundle: string, relativePath: string) => string;
+    writeDocument: (relativePath: string, content: string, bundle?: string) => void;
+    readFile: (relativePath: string) => string;
+    readSettings: () => string;
+    readLockfileText: () => string;
+    snapshot: () => ReadonlyArray<readonly [string, string]>;
+    provide: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E | import("@agentxm/workspace-state").WorkspaceMutationsError, FileSystem.FileSystem | import("effect/Path").Path | Exclude<R, import("./knowledge-index.ts").KnowledgeIndex | import("@agentxm/workspace-state/live").WorkspaceStateServices | import("@agentxm/workspace-state").WorkspaceMutations>>;
+    cleanup: () => void;
+};
+export type KnowledgeFixtureWorkspace = ReturnType<typeof makeKnowledgeFixtureWorkspace>;
+/** Capture the fixture workspace's corpus and return its snapshot. */
+export declare const captureFixtureSnapshot: (workspace: KnowledgeFixtureWorkspace) => Effect.Effect<import("./knowledge-index.ts").KnowledgeIndexSnapshot, import("./errors.ts").KnowledgeCorpusUnavailable | import("@agentxm/workspace-state").WorkspaceMutationsError, FileSystem.FileSystem | import("effect/Path").Path>;
+/** Each capture read sees another version through the production filesystem port. */
+export declare const withChangingKnowledgeReads: <A, E, R>(program: Effect.Effect<A, E, R>) => Effect.Effect<A, E, FileSystem.FileSystem | Exclude<R, FileSystem.FileSystem>>;
+//# sourceMappingURL=testing.d.ts.map

package/dist/src/testing.js

@@ -0,0 +1,139 @@
+/**
+ * @agentxm/knowledge-query deterministic fixtures and ports.
+ *
+ * A throwaway workspace with authored Knowledge bundles, the layer discovery
+ * needs over it, and the changing-source port that proves capture refuses an
+ * unstable corpus. Production source never imports this module.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as nodePath from "node:path";
+import * as ConfigProvider from "effect/ConfigProvider";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Ref from "effect/Ref";
+import { decodeAbsolutePathSync } from "@agentxm/extension-model/unstable/path-types";
+import { WorkspaceStateLive } from "@agentxm/workspace-state/live";
+import { captureInstalledKnowledgeCorpus } from "./corpus/installed-corpus.js";
+import { KnowledgeIndexLive } from "./live.js";
+export const knowledgeBundleFqn = "@acme/knowledge/platform";
+/** Minimal YAML emitter for fixture frontmatter: scalars and string arrays. */
+const yamlFrontmatter = (values) => Object.entries(values)
+    .map(([key, value]) => Array.isArray(value)
+    ? `${key}:\n${value.map((item) => `  - ${JSON.stringify(item)}`).join("\n")}\n`
+    : `${key}: ${JSON.stringify(value)}\n`)
+    .join("");
+/** An OKF concept document with fixture frontmatter and the given body. */
+export const knowledgeDocument = (body, frontmatter = {}) => `---\n${yamlFrontmatter({ type: "guide", description: "Fixture guidance", tags: ["fixture"], ...frontmatter })}---\n${body}`;
+/**
+ * The workspace-state services over the fixture, with a hermetic user home so
+ * the machine's real home is never read.
+ */
+const makeKnowledgeFixtureLayer = (root, home, scope) => Layer.provideMerge(Layer.merge(WorkspaceStateLive({
+    scope,
+    projectRoot: decodeAbsolutePathSync(root),
+    allowUninitialized: true,
+}), KnowledgeIndexLive), ConfigProvider.layer(ConfigProvider.fromEnv({ env: { AXM_USER_HOME: home } })));
+/**
+ * A project workspace whose Knowledge bundles are authored in place, exactly
+ * as `axm knowledge new` leaves them.
+ */
+export const makeKnowledgeFixtureWorkspace = (options = {}) => {
+    const bundles = options.bundles ?? [{ name: "platform", documents: {} }];
+    const root = fs.realpathSync(fs.mkdtempSync(nodePath.join(os.tmpdir(), "axm-knowledge-")));
+    const home = fs.realpathSync(fs.mkdtempSync(nodePath.join(os.tmpdir(), "axm-knowledge-home-")));
+    fs.mkdirSync(nodePath.join(root, ".axm"), { recursive: true });
+    fs.mkdirSync(nodePath.join(home, ".axm", "workspace"), { recursive: true });
+    const sourcePath = (bundle, relativePath) => nodePath.join(root, "knowledge", bundle, "src", relativePath);
+    const writeDocument = (relativePath, content, bundle = "platform") => {
+        const file = sourcePath(bundle, relativePath);
+        fs.mkdirSync(nodePath.dirname(file), { recursive: true });
+        fs.writeFileSync(file, content);
+    };
+    fs.writeFileSync(nodePath.join(root, "axm.json"), JSON.stringify({
+        agents: [],
+        // A workspace-sourced bundle names its owner through the workspace's own.
+        owner: "@acme",
+        knowledge: Object.fromEntries(bundles.map((bundle) => [
+            bundle.name,
+            {
+                source: "workspace",
+                enabled: bundle.enabled ?? true,
+                ...(bundle.instructionEntry === undefined
+                    ? {}
+                    : { instructionEntry: bundle.instructionEntry }),
+            },
+        ])),
+    }, null, 2));
+    // JSON is valid YAML, so the lockfile fixture needs no emitter.
+    fs.writeFileSync(nodePath.join(root, "axm-lock.yaml"), JSON.stringify({ lockfileVersion: 7, skills: {} }));
+    for (const bundle of bundles) {
+        const bundlePath = nodePath.join(root, "knowledge", bundle.name);
+        fs.mkdirSync(nodePath.join(bundlePath, "src"), { recursive: true });
+        fs.writeFileSync(nodePath.join(bundlePath, "knowledge.json"), JSON.stringify({
+            owner: "@acme",
+            type: "knowledge",
+            name: bundle.name,
+            version: "1.0.0",
+            description: "Fixture Knowledge bundle",
+            format: { name: "okf", version: "0.2" },
+            bundleRoot: "src",
+        }));
+        writeDocument("index.md", '---\nokf_version: "0.2"\n---\n# Fixture knowledge\n', bundle.name);
+        for (const [relativePath, content] of Object.entries(bundle.documents ?? {}))
+            writeDocument(relativePath, content, bundle.name);
+    }
+    const readFile = (relativePath) => fs.readFileSync(nodePath.join(root, relativePath), "utf8");
+    /** Every file under the workspace, so a read-only operation can be shown to write nothing. */
+    const snapshot = () => {
+        const entries = [];
+        const walk = (directory) => {
+            for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+                const absolute = nodePath.join(directory, entry.name);
+                if (entry.isDirectory())
+                    walk(absolute);
+                else
+                    entries.push([nodePath.relative(root, absolute), fs.readFileSync(absolute, "utf8")]);
+            }
+        };
+        walk(root);
+        return entries.sort((left, right) => left[0].localeCompare(right[0]));
+    };
+    const layer = makeKnowledgeFixtureLayer(root, home, options.scope ?? "project");
+    return {
+        root,
+        sourcePath,
+        writeDocument,
+        readFile,
+        readSettings: () => readFile("axm.json"),
+        readLockfileText: () => readFile("axm-lock.yaml"),
+        snapshot,
+        provide: (effect) => Effect.provide(effect, layer),
+        cleanup: () => {
+            fs.rmSync(root, { recursive: true, force: true });
+            fs.rmSync(home, { recursive: true, force: true });
+        },
+    };
+};
+/** Capture the fixture workspace's corpus and return its snapshot. */
+export const captureFixtureSnapshot = (workspace) => workspace.provide(captureInstalledKnowledgeCorpus().pipe(Effect.flatMap((captured) => captured.outcome === "ready"
+    ? Effect.succeed(captured.snapshot)
+    : Effect.die("fixture corpus kept changing"))));
+/** Each capture read sees another version through the production filesystem port. */
+export const withChangingKnowledgeReads = (program) => Effect.gen(function* () {
+    const filesystem = yield* FileSystem.FileSystem;
+    const reads = yield* Ref.make(0);
+    return yield* program.pipe(Effect.provideService(FileSystem.FileSystem, {
+        ...filesystem,
+        readFile: (filename) => filesystem
+            .readFile(filename)
+            .pipe(Effect.flatMap((bytes) => filename.endsWith(".md")
+            ? Ref.getAndUpdate(reads, (count) => count + 1).pipe(Effect.map((count) => new TextEncoder().encode(`${new TextDecoder().decode(bytes)}\nCapture version ${count}\n`)))
+            : Effect.succeed(bytes))),
+    }));
+});
+//# sourceMappingURL=testing.js.map

package/package.json

@@ -4,12 +4,15 @@
     "url": "https://github.com/agentxm/axm/issues"
   },
   "dependencies": {
-    "@agentxm/extension-model": "^0.28.11",
-    "@agentxm/registry-protocol": "^0.28.11",
+    "@agentxm/extension-content": "^0.28.13",
+    "@agentxm/extension-model": "^0.28.13",
+    "@agentxm/workspace-projection": "^0.28.13",
+    "@agentxm/workspace-state": "^0.28.13",
     "effect": "4.0.0-rc.112"
   },
   "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.",
   "devDependencies": {
+    "@agentxm/specification-metadata": "0.28.13",
     "@effect/platform-node": "4.0.0-rc.112",
     "@effect/vitest": "4.0.0-rc.112",
     "@types/bun": "^1.3.14",
@@ -30,6 +33,11 @@
       "axm-source": "./src/live.ts",
       "default": "./dist/src/live.js",
       "types": "./dist/src/live.d.ts"
+    },
+    "./testing": {
+      "axm-source": "./src/testing.ts",
+      "default": "./dist/src/testing.js",
+      "types": "./dist/src/testing.d.ts"
     }
   },
   "files": [
@@ -46,11 +54,11 @@
     "access": "public"
   },
   "repository": {
-    "directory": "packages/knowledge-query",
+    "directory": "packages/core/knowledge-query",
     "type": "git",
     "url": "https://github.com/agentxm/axm.git"
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.28.11"
-}
+  "version": "0.28.13"
+}