@agentxm/knowledge-query 0.28.11 → 0.28.13

package/dist/src/documents.d.ts

@@ -0,0 +1,349 @@
+/**
+ * The typed outcome documents Knowledge discovery reports.
+ *
+ * These are the feature's contract with automation: every discovery operation
+ * decodes its result through the schema declared here, and the application
+ * only wraps them in its envelope.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Schema from "effect/Schema";
+/** Preserve the core source mapping while validating JSON compatibility on encoding. */
+export declare const FrontmatterDocumentSchema: Schema.decodeTo<Schema.toType<Schema.$Record<Schema.String, Schema.Unknown>>, Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>, never, never>;
+export declare const KnowledgeConceptResultSchema: Schema.Struct<{
+    readonly ref: Schema.Struct<{
+        readonly bundle: Schema.String;
+        readonly conceptId: Schema.String;
+        readonly bundleVersion: Schema.String;
+        readonly bundleFingerprint: Schema.String;
+        readonly contentRevision: Schema.String;
+    }>;
+    readonly orderingKey: Schema.String;
+    readonly matchedFields: Schema.$Array<Schema.String>;
+    readonly passages: Schema.$Array<Schema.Struct<{
+        readonly text: Schema.String;
+        readonly section: Schema.$Array<Schema.String>;
+        readonly startLine: Schema.Number;
+        readonly endLine: Schema.Number;
+        readonly spans: Schema.$Array<Schema.Struct<{
+            readonly clauseIndex: Schema.Number;
+            readonly field: Schema.String;
+            readonly start: Schema.Number;
+            readonly end: Schema.Number;
+        }>>;
+    }>>;
+    readonly kind: Schema.Literals<readonly ["concept", "index", "log"]>;
+    readonly title: Schema.optional<Schema.String>;
+    readonly description: Schema.optional<Schema.String>;
+    readonly status: Schema.optional<Schema.String>;
+    readonly staleAfter: Schema.optional<Schema.String>;
+    readonly generated: Schema.optional<Schema.Struct<{
+        readonly by: Schema.String;
+        readonly at: Schema.optional<Schema.String>;
+    }>>;
+    readonly verified: Schema.optional<Schema.$Array<Schema.Struct<{
+        readonly by: Schema.String;
+        readonly at: Schema.optional<Schema.String>;
+    }>>>;
+    readonly trust: Schema.optional<Schema.Literals<readonly ["unverified", "machine-confirmed", "human-reviewed"]>>;
+    readonly relativePath: Schema.String;
+}>;
+export declare const KnowledgeConceptQueryPageSchema: Schema.Struct<{
+    readonly query: 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>;
+    }>;
+    readonly corpusFingerprint: Schema.String;
+    readonly items: Schema.$Array<Schema.Struct<{
+        readonly ref: Schema.Struct<{
+            readonly bundle: Schema.String;
+            readonly conceptId: Schema.String;
+            readonly bundleVersion: Schema.String;
+            readonly bundleFingerprint: Schema.String;
+            readonly contentRevision: Schema.String;
+        }>;
+        readonly orderingKey: Schema.String;
+        readonly matchedFields: Schema.$Array<Schema.String>;
+        readonly passages: Schema.$Array<Schema.Struct<{
+            readonly text: Schema.String;
+            readonly section: Schema.$Array<Schema.String>;
+            readonly startLine: Schema.Number;
+            readonly endLine: Schema.Number;
+            readonly spans: Schema.$Array<Schema.Struct<{
+                readonly clauseIndex: Schema.Number;
+                readonly field: Schema.String;
+                readonly start: Schema.Number;
+                readonly end: Schema.Number;
+            }>>;
+        }>>;
+        readonly kind: Schema.Literals<readonly ["concept", "index", "log"]>;
+        readonly title: Schema.optional<Schema.String>;
+        readonly description: Schema.optional<Schema.String>;
+        readonly status: Schema.optional<Schema.String>;
+        readonly staleAfter: Schema.optional<Schema.String>;
+        readonly generated: Schema.optional<Schema.Struct<{
+            readonly by: Schema.String;
+            readonly at: Schema.optional<Schema.String>;
+        }>>;
+        readonly verified: Schema.optional<Schema.$Array<Schema.Struct<{
+            readonly by: Schema.String;
+            readonly at: Schema.optional<Schema.String>;
+        }>>>;
+        readonly trust: Schema.optional<Schema.Literals<readonly ["unverified", "machine-confirmed", "human-reviewed"]>>;
+        readonly relativePath: Schema.String;
+    }>>;
+    readonly count: Schema.Number;
+    readonly hasMore: Schema.Boolean;
+    readonly cursor: Schema.optional<Schema.String>;
+    readonly explanation: Schema.optional<Schema.Struct<{
+        readonly strategy: Schema.Literal<"lexical">;
+        readonly ordering: Schema.Literals<readonly ["relevance", "metadata"]>;
+        readonly rankFactors: Schema.$Array<Schema.Struct<{
+            readonly field: Schema.String;
+            readonly weight: Schema.Number;
+        }>>;
+        readonly tieBreak: Schema.String;
+    }>>;
+}>;
+export type KnowledgeConceptQueryPage = typeof KnowledgeConceptQueryPageSchema.Type;
+export declare const KnowledgeConceptGetOutputSchema: Schema.Struct<{
+    readonly outcome: Schema.Literals<readonly ["found", "failed"]>;
+    readonly concept: Schema.optional<Schema.Struct<{
+        readonly ref: Schema.Struct<{
+            readonly bundle: Schema.String;
+            readonly conceptId: Schema.String;
+            readonly bundleVersion: Schema.String;
+            readonly bundleFingerprint: Schema.String;
+            readonly contentRevision: Schema.String;
+        }>;
+        readonly projectionRevision: Schema.String;
+        readonly kind: Schema.Literals<readonly ["concept", "index", "log"]>;
+        readonly title: Schema.optional<Schema.String>;
+        readonly type: Schema.optional<Schema.String>;
+        readonly description: Schema.optional<Schema.String>;
+        readonly tags: Schema.optional<Schema.$Array<Schema.String>>;
+        readonly resource: Schema.optional<Schema.String>;
+        readonly status: Schema.optional<Schema.String>;
+        readonly staleAfter: Schema.optional<Schema.String>;
+        readonly generated: Schema.optional<Schema.Struct<{
+            readonly by: Schema.String;
+            readonly at: Schema.optional<Schema.String>;
+        }>>;
+        readonly verified: Schema.optional<Schema.$Array<Schema.Struct<{
+            readonly by: Schema.String;
+            readonly at: Schema.optional<Schema.String>;
+        }>>>;
+        readonly trust: Schema.optional<Schema.Literals<readonly ["unverified", "machine-confirmed", "human-reviewed"]>>;
+        readonly frontmatter: Schema.optional<Schema.decodeTo<Schema.toType<Schema.$Record<Schema.String, Schema.Unknown>>, Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>, never, never>>;
+        readonly relativePath: Schema.String;
+        readonly body: Schema.String;
+        readonly raw: Schema.optional<Schema.String>;
+    }>>;
+    readonly reason: Schema.optional<Schema.Literal<"revision-changed">>;
+    readonly ref: Schema.optional<Schema.Struct<{
+        readonly bundle: Schema.String;
+        readonly conceptId: Schema.String;
+        readonly bundleVersion: Schema.String;
+        readonly bundleFingerprint: Schema.String;
+        readonly contentRevision: Schema.String;
+    }>>;
+    readonly expectedRevision: Schema.optional<Schema.String>;
+    readonly currentRevision: Schema.optional<Schema.String>;
+}>;
+export type KnowledgeConceptGetOutput = typeof KnowledgeConceptGetOutputSchema.Type;
+export declare const KnowledgeConceptResolveOutputSchema: Schema.Struct<{
+    readonly outcome: Schema.Literals<readonly ["resolved", "ambiguous", "not-found"]>;
+    readonly reason: Schema.optional<Schema.Literal<"ambiguous-reference">>;
+    readonly candidate: Schema.optional<Schema.Struct<{
+        readonly ref: Schema.Struct<{
+            readonly bundle: Schema.String;
+            readonly conceptId: Schema.String;
+            readonly bundleVersion: Schema.String;
+            readonly bundleFingerprint: Schema.String;
+            readonly contentRevision: Schema.String;
+        }>;
+        readonly title: Schema.optional<Schema.String>;
+        readonly reason: Schema.Literals<readonly ["exact-reference", "exact-concept-id", "exact-title", "token-match"]>;
+        readonly score: Schema.Number;
+        readonly orderingKey: Schema.String;
+    }>>;
+    readonly candidates: Schema.optional<Schema.$Array<Schema.Struct<{
+        readonly ref: Schema.Struct<{
+            readonly bundle: Schema.String;
+            readonly conceptId: Schema.String;
+            readonly bundleVersion: Schema.String;
+            readonly bundleFingerprint: Schema.String;
+            readonly contentRevision: Schema.String;
+        }>;
+        readonly title: Schema.optional<Schema.String>;
+        readonly reason: Schema.Literals<readonly ["exact-reference", "exact-concept-id", "exact-title", "token-match"]>;
+        readonly score: Schema.Number;
+        readonly orderingKey: Schema.String;
+    }>>>;
+}>;
+export type KnowledgeConceptResolveOutput = typeof KnowledgeConceptResolveOutputSchema.Type;
+export declare const KnowledgeConceptRelatedOutputSchema: Schema.Struct<{
+    readonly ref: Schema.Struct<{
+        readonly bundle: Schema.String;
+        readonly conceptId: Schema.String;
+        readonly bundleVersion: Schema.String;
+        readonly bundleFingerprint: Schema.String;
+        readonly contentRevision: Schema.String;
+    }>;
+    readonly maximumDepth: Schema.Number;
+    readonly includesIndexBacklinks: Schema.Boolean;
+    readonly items: Schema.$Array<Schema.Struct<{
+        readonly ref: Schema.Struct<{
+            readonly bundle: Schema.String;
+            readonly conceptId: Schema.String;
+            readonly bundleVersion: Schema.String;
+            readonly bundleFingerprint: Schema.String;
+            readonly contentRevision: Schema.String;
+        }>;
+        readonly title: Schema.optional<Schema.String>;
+        readonly relation: Schema.Literals<readonly ["outgoing", "backlink"]>;
+        readonly depth: Schema.Number;
+        readonly via: Schema.Struct<{
+            readonly bundle: Schema.String;
+            readonly conceptId: Schema.String;
+        }>;
+        readonly evidence: Schema.Struct<{
+            readonly source: Schema.Struct<{
+                readonly bundle: Schema.String;
+                readonly conceptId: Schema.String;
+            }>;
+            readonly sourceRelativePath: Schema.String;
+            readonly line: Schema.Number;
+        }>;
+        readonly orderingKey: Schema.String;
+    }>>;
+    readonly count: Schema.Number;
+    readonly corpusFingerprint: Schema.String;
+}>;
+export type KnowledgeConceptRelatedOutput = typeof KnowledgeConceptRelatedOutputSchema.Type;
+export declare const KnowledgeConceptStatusOutputSchema: Schema.Struct<{
+    readonly capabilities: 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"]>>;
+        }>;
+    }>;
+    readonly readiness: Schema.Literals<readonly ["ready", "changing", "unavailable"]>;
+    readonly health: Schema.Struct<{
+        readonly status: Schema.Literals<readonly ["healthy", "unhealthy"]>;
+        readonly diagnostics: Schema.$Array<Schema.String>;
+    }>;
+    readonly corpusFingerprint: Schema.optional<Schema.String>;
+    readonly bundleCount: Schema.Number;
+    readonly conceptCount: Schema.Number;
+    readonly scopeCollisions: Schema.Struct<{
+        readonly checkedScope: Schema.Literals<readonly ["project", "user"]>;
+        readonly state: Schema.Literals<readonly ["determined", "not-determined"]>;
+        readonly bundleNames: Schema.$Array<Schema.String>;
+    }>;
+}>;
+export type KnowledgeConceptStatusOutput = typeof KnowledgeConceptStatusOutputSchema.Type;
+export declare const KnowledgeLintQueryResultSchema: Schema.Struct<{
+    readonly valid: Schema.Boolean;
+    readonly diagnostics: Schema.$Array<Schema.Struct<{
+        readonly bundle: Schema.String;
+        readonly code: Schema.String;
+        readonly severity: Schema.String;
+        readonly relativePath: Schema.String;
+        readonly line: Schema.optional<Schema.Number>;
+        readonly column: Schema.optional<Schema.Number>;
+        readonly message: Schema.String;
+        readonly details: Schema.optional<Schema.Struct<{
+            readonly kind: Schema.Literal<"frontmatter-parse">;
+            readonly reason: Schema.String;
+        }>>;
+    }>>;
+}>;
+export type KnowledgeLintQueryResult = typeof KnowledgeLintQueryResultSchema.Type;
+export declare const KnowledgeConceptCursorFailureSchema: Schema.Struct<{
+    readonly outcome: Schema.Literal<"failed">;
+    readonly reason: Schema.Literal<"cursor-expired">;
+}>;
+export declare const KnowledgeConceptCorpusChangingFailureSchema: Schema.Struct<{
+    readonly outcome: Schema.Literal<"failed">;
+    readonly reason: Schema.Literal<"corpus-changing">;
+}>;
+//# sourceMappingURL=documents.d.ts.map

package/dist/src/documents.js

@@ -0,0 +1,168 @@
+/**
+ * The typed outcome documents Knowledge discovery reports.
+ *
+ * These are the feature's contract with automation: every discovery operation
+ * decodes its result through the schema declared here, and the application
+ * only wraps them in its envelope.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as SchemaParser from "effect/SchemaParser";
+import * as SchemaTransformation from "effect/SchemaTransformation";
+import { ConceptRefSchema, KnowledgeRevisionSchema, ResolvedConceptRefSchema, } from "@agentxm/extension-model/unstable/knowledge";
+import { KnowledgeDiscoveryCapabilitiesSchema } from "./knowledge-capabilities.js";
+import { KnowledgeQuerySchema } from "./knowledge-query.js";
+const FrontmatterWireSchema = Schema.Record(Schema.String, Schema.Json);
+/** Preserve the core source mapping while validating JSON compatibility on encoding. */
+export const FrontmatterDocumentSchema = FrontmatterWireSchema.pipe(Schema.decodeTo(Schema.toType(Schema.Record(Schema.String, Schema.Unknown)), SchemaTransformation.transformOrFail({
+    decode: (frontmatter) => Effect.succeed(frontmatter),
+    encode: (frontmatter) => SchemaParser.decodeUnknownEffect(FrontmatterWireSchema)(frontmatter),
+})));
+const KnowledgeActorSchema = Schema.Struct({
+    by: Schema.String,
+    at: Schema.optional(Schema.String),
+});
+const KnowledgeMatchSpanSchema = Schema.Struct({
+    clauseIndex: Schema.Number,
+    field: Schema.String,
+    start: Schema.Number,
+    end: Schema.Number,
+});
+const KnowledgePassageSchema = Schema.Struct({
+    text: Schema.String,
+    section: Schema.Array(Schema.String),
+    startLine: Schema.Number,
+    endLine: Schema.Number,
+    spans: Schema.Array(KnowledgeMatchSpanSchema),
+});
+export const KnowledgeConceptResultSchema = Schema.Struct({
+    ref: ResolvedConceptRefSchema,
+    orderingKey: Schema.String,
+    matchedFields: Schema.Array(Schema.String),
+    passages: Schema.Array(KnowledgePassageSchema),
+    kind: Schema.Literals(["concept", "index", "log"]),
+    title: Schema.optional(Schema.String),
+    description: Schema.optional(Schema.String),
+    status: Schema.optional(Schema.String),
+    staleAfter: Schema.optional(Schema.String),
+    generated: Schema.optional(KnowledgeActorSchema),
+    verified: Schema.optional(Schema.Array(KnowledgeActorSchema)),
+    trust: Schema.optional(Schema.Literals(["unverified", "machine-confirmed", "human-reviewed"])),
+    relativePath: Schema.String,
+});
+export const KnowledgeConceptQueryPageSchema = Schema.Struct({
+    query: KnowledgeQuerySchema,
+    corpusFingerprint: KnowledgeRevisionSchema,
+    items: Schema.Array(KnowledgeConceptResultSchema),
+    count: Schema.Number,
+    hasMore: Schema.Boolean,
+    cursor: Schema.optional(Schema.String),
+    explanation: Schema.optional(Schema.Struct({
+        strategy: Schema.Literal("lexical"),
+        ordering: Schema.Literals(["relevance", "metadata"]),
+        rankFactors: Schema.Array(Schema.Struct({ field: Schema.String, weight: Schema.Number })),
+        tieBreak: Schema.String,
+    })),
+});
+const KnowledgeConceptDocumentSchema = Schema.Struct({
+    ref: ResolvedConceptRefSchema,
+    projectionRevision: KnowledgeRevisionSchema,
+    kind: Schema.Literals(["concept", "index", "log"]),
+    title: Schema.optional(Schema.String),
+    type: Schema.optional(Schema.String),
+    description: Schema.optional(Schema.String),
+    tags: Schema.optional(Schema.Array(Schema.String)),
+    resource: Schema.optional(Schema.String),
+    status: Schema.optional(Schema.String),
+    staleAfter: Schema.optional(Schema.String),
+    generated: Schema.optional(KnowledgeActorSchema),
+    verified: Schema.optional(Schema.Array(KnowledgeActorSchema)),
+    trust: Schema.optional(Schema.Literals(["unverified", "machine-confirmed", "human-reviewed"])),
+    frontmatter: Schema.optional(FrontmatterDocumentSchema),
+    relativePath: Schema.String,
+    body: Schema.String,
+    raw: Schema.optional(Schema.String),
+});
+export const KnowledgeConceptGetOutputSchema = Schema.Struct({
+    outcome: Schema.Literals(["found", "failed"]),
+    concept: Schema.optional(KnowledgeConceptDocumentSchema),
+    reason: Schema.optional(Schema.Literal("revision-changed")),
+    ref: Schema.optional(ResolvedConceptRefSchema),
+    expectedRevision: Schema.optional(KnowledgeRevisionSchema),
+    currentRevision: Schema.optional(KnowledgeRevisionSchema),
+});
+const KnowledgeResolveCandidateSchema = Schema.Struct({
+    ref: ResolvedConceptRefSchema,
+    title: Schema.optional(Schema.String),
+    reason: Schema.Literals(["exact-reference", "exact-concept-id", "exact-title", "token-match"]),
+    score: Schema.Number,
+    orderingKey: Schema.String,
+});
+export const KnowledgeConceptResolveOutputSchema = Schema.Struct({
+    outcome: Schema.Literals(["resolved", "ambiguous", "not-found"]),
+    reason: Schema.optional(Schema.Literal("ambiguous-reference")),
+    candidate: Schema.optional(KnowledgeResolveCandidateSchema),
+    candidates: Schema.optional(Schema.Array(KnowledgeResolveCandidateSchema)),
+});
+const KnowledgeRelatedConceptSchema = Schema.Struct({
+    ref: ResolvedConceptRefSchema,
+    title: Schema.optional(Schema.String),
+    relation: Schema.Literals(["outgoing", "backlink"]),
+    depth: Schema.Number,
+    via: ConceptRefSchema,
+    evidence: Schema.Struct({
+        source: ConceptRefSchema,
+        sourceRelativePath: Schema.String,
+        line: Schema.Number,
+    }),
+    orderingKey: Schema.String,
+});
+export const KnowledgeConceptRelatedOutputSchema = Schema.Struct({
+    ref: ResolvedConceptRefSchema,
+    maximumDepth: Schema.Number,
+    includesIndexBacklinks: Schema.Boolean,
+    items: Schema.Array(KnowledgeRelatedConceptSchema),
+    count: Schema.Number,
+    corpusFingerprint: KnowledgeRevisionSchema,
+});
+export const KnowledgeConceptStatusOutputSchema = Schema.Struct({
+    capabilities: KnowledgeDiscoveryCapabilitiesSchema,
+    readiness: Schema.Literals(["ready", "changing", "unavailable"]),
+    health: Schema.Struct({
+        status: Schema.Literals(["healthy", "unhealthy"]),
+        diagnostics: Schema.Array(Schema.String),
+    }),
+    corpusFingerprint: Schema.optional(KnowledgeRevisionSchema),
+    bundleCount: Schema.Number,
+    conceptCount: Schema.Number,
+    scopeCollisions: Schema.Struct({
+        checkedScope: Schema.Literals(["project", "user"]),
+        state: Schema.Literals(["determined", "not-determined"]),
+        bundleNames: Schema.Array(Schema.String),
+    }),
+});
+const KnowledgeLintDiagnosticSchema = Schema.Struct({
+    bundle: Schema.String,
+    code: Schema.String,
+    severity: Schema.String,
+    relativePath: Schema.String,
+    line: Schema.optional(Schema.Number),
+    column: Schema.optional(Schema.Number),
+    message: Schema.String,
+    details: Schema.optional(Schema.Struct({ kind: Schema.Literal("frontmatter-parse"), reason: Schema.String })),
+});
+export const KnowledgeLintQueryResultSchema = Schema.Struct({
+    valid: Schema.Boolean,
+    diagnostics: Schema.Array(KnowledgeLintDiagnosticSchema),
+});
+export const KnowledgeConceptCursorFailureSchema = Schema.Struct({
+    outcome: Schema.Literal("failed"),
+    reason: Schema.Literal("cursor-expired"),
+});
+export const KnowledgeConceptCorpusChangingFailureSchema = Schema.Struct({
+    outcome: Schema.Literal("failed"),
+    reason: Schema.Literal("corpus-changing"),
+});
+//# sourceMappingURL=documents.js.map

package/dist/src/errors.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The typed failures Knowledge discovery reports to its caller.
+ *
+ * Every one carries the facts a caller needs to recover or render: what was
+ * refused, and why. The CLI maps them onto exit codes and envelopes; it never
+ * re-derives the decision.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+declare const KnowledgeRequestInvalid_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: "KnowledgeRequestInvalid";
+} & Readonly<A>;
+/** A discovery request that the published grammar or bounds refuse. */
+export declare class KnowledgeRequestInvalid extends KnowledgeRequestInvalid_base<{
+    readonly detail: string;
+}> {
+}
+declare const KnowledgeCorpusUnavailable_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: "KnowledgeCorpusUnavailable";
+} & Readonly<A>;
+/** The selected installed corpus could not be captured. */
+export declare class KnowledgeCorpusUnavailable extends KnowledgeCorpusUnavailable_base<{
+    readonly reason: "desired-state-incomplete" | "bundle-not-installed" | "source-unreadable";
+    readonly detail: string;
+    readonly bundle?: string;
+    readonly cause?: unknown;
+}> {
+}
+declare const KnowledgeConceptNotFound_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: "KnowledgeConceptNotFound";
+} & Readonly<A>;
+/** An exact concept reference named nothing in the selected corpus. */
+export declare class KnowledgeConceptNotFound extends KnowledgeConceptNotFound_base<{
+    readonly reference: string;
+}> {
+}
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/errors.js

@@ -0,0 +1,20 @@
+/**
+ * The typed failures Knowledge discovery reports to its caller.
+ *
+ * Every one carries the facts a caller needs to recover or render: what was
+ * refused, and why. The CLI maps them onto exit codes and envelopes; it never
+ * re-derives the decision.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Data from "effect/Data";
+/** A discovery request that the published grammar or bounds refuse. */
+export class KnowledgeRequestInvalid extends Data.TaggedError("KnowledgeRequestInvalid") {
+}
+/** The selected installed corpus could not be captured. */
+export class KnowledgeCorpusUnavailable extends Data.TaggedError("KnowledgeCorpusUnavailable") {
+}
+/** An exact concept reference named nothing in the selected corpus. */
+export class KnowledgeConceptNotFound extends Data.TaggedError("KnowledgeConceptNotFound") {
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/index.d.ts

@@ -3,6 +3,13 @@ export { projectKnowledgeConcepts, resolveKnowledgeFrontmatterPointer, type Know
 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 { getKnowledgeIndexConcept, KnowledgeCursorInvalidError, KnowledgeIndex, KNOWLEDGE_RANK_FACTORS, KNOWLEDGE_RANK_TIE_BREAK, 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";
+export { KnowledgeConceptNotFound, KnowledgeCorpusUnavailable, KnowledgeRequestInvalid, } from "./errors.js";
+export { FrontmatterDocumentSchema, KnowledgeConceptCorpusChangingFailureSchema, KnowledgeConceptCursorFailureSchema, KnowledgeConceptGetOutputSchema, KnowledgeConceptQueryPageSchema, KnowledgeConceptRelatedOutputSchema, KnowledgeConceptResolveOutputSchema, KnowledgeConceptResultSchema, KnowledgeConceptStatusOutputSchema, KnowledgeLintQueryResultSchema, type KnowledgeConceptGetOutput, type KnowledgeConceptQueryPage, type KnowledgeConceptRelatedOutput, type KnowledgeConceptResolveOutput, type KnowledgeConceptStatusOutput, type KnowledgeLintQueryResult, } from "./documents.js";
+export { captureInstalledKnowledgeCorpus, type CapturedInstalledBundle, type InstalledKnowledgeCorpus, } from "./corpus/installed-corpus.js";
+export { reportKnowledgeCorpusStatus } from "./corpus/corpus-status.js";
+export { lintKnowledge, type LintKnowledgeRequest, type LintKnowledgeResult, } from "./lint/lint-knowledge.js";
+export { checkTraversalDepth, explainKnowledgeQuery, makeKnowledgeQueryRequest, makeKnowledgeSearchRequest, type KnowledgeQueryExplanation, type KnowledgeQueryRequest, type KnowledgeSearchRequest, } from "./query/request.js";
+export { KnowledgeDiscovery } from "./knowledge-discovery.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/index.js

@@ -3,6 +3,14 @@ export { projectKnowledgeConcepts, resolveKnowledgeFrontmatterPointer, } from ".
 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 { getKnowledgeIndexConcept, KnowledgeCursorInvalidError, KnowledgeIndex, KNOWLEDGE_RANK_FACTORS, KNOWLEDGE_RANK_TIE_BREAK, makeKnowledgeIndexSnapshot, queryKnowledgeIndex, queryKnowledgeIndexResult, } from "./knowledge-index.js";
 export { captureKnowledgeIndexBundles, KnowledgeCapturedSourceMissingError, } from "./knowledge-capture.js";
+// Typed failures, outcome documents, and the read-only application API.
+export { KnowledgeConceptNotFound, KnowledgeCorpusUnavailable, KnowledgeRequestInvalid, } from "./errors.js";
+export { FrontmatterDocumentSchema, KnowledgeConceptCorpusChangingFailureSchema, KnowledgeConceptCursorFailureSchema, KnowledgeConceptGetOutputSchema, KnowledgeConceptQueryPageSchema, KnowledgeConceptRelatedOutputSchema, KnowledgeConceptResolveOutputSchema, KnowledgeConceptResultSchema, KnowledgeConceptStatusOutputSchema, KnowledgeLintQueryResultSchema, } from "./documents.js";
+export { captureInstalledKnowledgeCorpus, } from "./corpus/installed-corpus.js";
+export { reportKnowledgeCorpusStatus } from "./corpus/corpus-status.js";
+export { lintKnowledge, } from "./lint/lint-knowledge.js";
+export { checkTraversalDepth, explainKnowledgeQuery, makeKnowledgeQueryRequest, makeKnowledgeSearchRequest, } from "./query/request.js";
+export { KnowledgeDiscovery } from "./knowledge-discovery.js";
 //# sourceMappingURL=index.js.map

package/dist/src/knowledge-capabilities.js

@@ -1,5 +1,5 @@
 import * as Schema from "effect/Schema";
-import { KNOWLEDGE_SEARCH_TOKENIZER_PROFILE } from "@agentxm/registry-protocol/unstable/knowledge/knowledge-search";
+import { KNOWLEDGE_SEARCH_TOKENIZER_PROFILE } from "@agentxm/extension-content/knowledge";
 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({

package/dist/src/knowledge-capture.js

@@ -4,7 +4,7 @@ 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";
+import { collectKnowledgeBundleEntries, inspectKnowledgeEntries, } from "@agentxm/extension-content/knowledge";
 export class KnowledgeCapturedSourceMissingError extends Data.TaggedError("KnowledgeCapturedSourceMissingError") {
 }
 const sourceKey = (bundle, relativePath) => `${bundle.length}:${bundle}${relativePath.length}:${relativePath}`;