//! Static handler descriptor table for the knowledge pack (19 verbs + 1 subhandler).
use khive_types::{HandlerDef, IdResolutionMode, ParamDef, VerbCategory, Visibility};
/// Pack-owned schema for persisted retrieval-evaluation summaries.
///
/// These statements stay in the Knowledge pack's schema plan rather than the
/// core migration ledger so multi-backend boot applies them to Knowledge's
/// assigned backend. Both statements are idempotent for repeated startup.
pub(crate) static KNOWLEDGE_SCHEMA_PLAN_STMTS: [&str; 2] = [
khive_runtime::sql!("knowledge_eval_runs_create"),
khive_runtime::sql!("knowledge_eval_runs_ns_run_at_index"),
];
pub(crate) static KNOWLEDGE_HANDLERS: [HandlerDef; 20] = [
// ── corpus tier ──────────────────────────────────────────────────────────
HandlerDef {
name: "knowledge.upsert_atoms",
description: "Atomically insert or update knowledge atoms by slug, or replace existing atom properties by UUID. All inputs are validated before writing; a validation or secret refusal commits no atom writes. dry_run=true returns every item's validation verdict without writing atoms, indexes or refusal events; host dispatch auditing may still record the call. Secret refusals identify the zero-based atoms[index].field; valid siblings are not partially committed.",
visibility: Visibility::Verb,
category: VerbCategory::Commissive,
params: &[
ParamDef {
name: "atoms",
param_type: "array of object",
required: true,
description: "List of atom writes. Content form: {slug, name, content, tags?, properties?, source_uri?, source_type?, finalized?}; content requires at least 20 words, omitted source/finalized fields are preserved, and null clears a source or resets finalized without demoting lifecycle status. Properties-only form: exactly {id: complete UUID, properties: JSON value or null}; replaces properties on an existing live ordinary atom across namespaces while preserving all other fields except updated_at. Missing/deleted IDs are NotFound; domains and mirrors are refused. Forms may mix in one atomic batch and apply in input order.",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "chunk_size",
param_type: "integer",
required: false,
description: "Per-chunk size for client-side chunking hint (max 5000)",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "dry_run",
param_type: "boolean",
required: false,
description: "Default false. True checks the whole batch and returns indexed results with would_refuse plus would_refuse_batch, without atom/index writes or refusal events. Secret details and secret-bearing identities are masked.",
resolution_mode: IdResolutionMode::NotApplicable,
},
],
},
HandlerDef {
name: "knowledge.upsert_domains",
description: "Bulk insert or update domain groupings of atoms",
visibility: Visibility::Verb,
category: VerbCategory::Commissive,
params: &[ParamDef {
name: "domains",
param_type: "array of object",
required: true,
description: "List of domains: {slug, name, description?, tags?, members?}",
resolution_mode: IdResolutionMode::NotApplicable,
}],
},
HandlerDef {
name: "knowledge.get",
description: "Fetch a single atom or domain by UUID, exact slug, or unique short prefix",
visibility: Visibility::Verb,
category: VerbCategory::Assertive,
params: &[
ParamDef {
name: "id",
param_type: "string",
required: true,
description: "Atom/domain full UUID, exact slug, or unique 8+ hex UUID prefix. Resolution order is full UUID, exact caller-namespace slug, then prefix. UUID and prefix forms are namespace-agnostic by-ID reads.",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "include_sections",
param_type: "boolean",
required: false,
description: "When true, include the atom's sections under a `sections` key. Each section object contains: id, atom_id, namespace, section_type, heading, content, content_hash, status, tokens, sort_order, created_at, updated_at. Ordered by sort_order ASC, created_at ASC, id ASC. Ignored for domains. Default: false.",
resolution_mode: IdResolutionMode::NotApplicable,
},
],
},
HandlerDef {
name: "knowledge.list",
description: "Paginated listing of atoms or domains. Legacy offset pages use the declared \
created_at DESC, id DESC order. For complete walks use after=\"\" and \
round-trip next_after; cursor pages seek by created_at ASC, id ASC and are \
not shifted by concurrent inserts.",
visibility: Visibility::Verb,
category: VerbCategory::Assertive,
params: &[
ParamDef {
name: "type",
param_type: "string",
required: false,
description: "Filter: \"atom\" | \"domain\" (default: atom)",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "limit",
param_type: "integer",
required: false,
description: "Max results (default 20, max 500)",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "offset",
param_type: "integer",
required: false,
description: "Pagination offset (default 0), ordered by created_at DESC then id DESC. \
Prefer after for full-store walks; offset and after are mutually exclusive.",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "after",
param_type: "string",
required: false,
description: "Keyset cursor for a stable full-store walk. Pass \"\" to start, then \
round-trip the prior page's next_after full UUID. Cursor pages use \
created_at ASC, id ASC. This is a live traversal: inserts behind an \
issued boundary belong to a fresh walk; inserts ahead may extend the \
current walk. Reuse the same type/status/fields filters. Soft-deleting \
a boundary does not invalidate it; missing, wrong-type, or out-of-namespace \
cursors fail. Stop when next_after is null; cursor pages carry no total \
(counting is a full scan per page). Mutually exclusive with offset.",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "fields",
param_type: "array of string",
required: false,
description: "Non-empty exact response projection. Atom fields: id, namespace, slug, \
name, content, tags, properties, status, source_uri, source_type, finalized, \
kind, created_at, updated_at. Domain fields: id, namespace, slug, name, \
description, tags, members, kind, created_at, updated_at. Unknown fields \
fail. Storage selects only requested columns plus hidden pagination keys; \
use [\"id\",\"slug\"] for efficient inventory walks.",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "status",
param_type: "string | array<string>",
required: false,
description: "Filter atoms to this status or set of statuses (e.g. \"draft\" or [\"draft\",\"reviewed\"]). Ignored for domains.",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "exclude_status",
param_type: "string",
required: false,
description: "Exclude atoms with this exact status. Only used when status= is not set. Ignored for domains.",
resolution_mode: IdResolutionMode::NotApplicable,
},
],
},
HandlerDef {
name: "knowledge.delete_atoms",
description: "Soft-delete atoms by slug or ID",
visibility: Visibility::Verb,
category: VerbCategory::Commissive,
params: &[
ParamDef {
name: "ids",
param_type: "array of string",
required: true,
description: "Atom slugs or UUIDs to delete",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "cascade",
param_type: "boolean",
required: false,
description: "Deprecated no-op. Accepted for API compatibility but not yet implemented; sections are not cascade-deleted when atoms are soft-deleted.",
resolution_mode: IdResolutionMode::NotApplicable,
},
],
},
HandlerDef {
name: "knowledge.stats",
description: "Corpus statistics: atom count, domain count, coverage",
visibility: Visibility::Verb,
category: VerbCategory::Assertive,
params: &[],
},
HandlerDef {
name: "knowledge.eval_retrieval",
description: "Run a labeled, draft-inclusive atom-retrieval query set and persist aggregate quality metrics",
visibility: Visibility::Subhandler,
category: VerbCategory::Commissive,
params: &[ParamDef {
name: "query_set",
param_type: "string",
required: true,
description: "Absolute path to a TOML query set containing query and expected_slugs entries",
resolution_mode: IdResolutionMode::NotApplicable,
}],
},
HandlerDef {
name: "knowledge.index",
description: "Backfill atom embeddings. Does not rebuild the global FTS indexes: that is a whole-database operation independent of the caller's namespace, with no per-caller cost admission on this verb, so it is reachable only through the `kkernel reindex` operator CLI (`--rebuild-fts`).",
visibility: Visibility::Verb,
category: VerbCategory::Commissive,
params: &[
ParamDef {
name: "ids",
param_type: "array of string",
required: false,
description: "Atom slugs/IDs to index. Omit to index all.",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "batch_size",
param_type: "integer",
required: false,
description: "Page size for whole-corpus indexing (default 500, max 1000)",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "insert_only",
param_type: "boolean",
required: false,
description: "Deprecated no-op. Accepted for API compatibility but no longer drives any pre-delete behavior; SqliteVecStore::insert atomically replaces regardless of this flag.",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "rebuild_ann",
param_type: "boolean",
required: false,
description: "Rebuild in-memory Vamana ANN index from embeddings (default false)",
resolution_mode: IdResolutionMode::NotApplicable,
},
],
},
HandlerDef {
name: "knowledge.fold",
description: "Budget-constrained knapsack selection of scored candidates",
visibility: Visibility::Verb,
category: VerbCategory::Assertive,
params: &[
ParamDef {
name: "candidates",
param_type: "array of object",
required: true,
description: "Scored items: {id, score, size, name?, members?, content?, category?, information_gain?}. `members` is an optional live member count; candidates with members=0 are not selected. `knowledge.suggest`'s `results` feed this directly.",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "budget",
param_type: "integer",
required: true,
description: "Token/size budget for the selected set",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "min_score",
param_type: "number",
required: false,
description: "Minimum score threshold (default 0.0)",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "category_weights",
param_type: "object",
required: false,
description: "Per-category score multipliers",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "diversity_bias",
param_type: "number",
required: false,
description: "Selector diversity bias weight (default 0.0; must be finite)",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "epistemic_weight",
param_type: "number",
required: false,
description: "Selector weight applied to each candidate's information_gain (default 0.0; must be finite)",
resolution_mode: IdResolutionMode::NotApplicable,
},
],
},
HandlerDef {
name: "knowledge.search",
description: "TF-IDF ranked search over the atom teaching corpus ONLY — knowledge graph entities and notes are a disjoint corpus and are never returned here; use the kg pack's `search` verb for those. Embedding rerank applies by default when an embedder is configured. A genuine FTS miss returns no lexical candidates instead of scanning newest corpus rows; a healthy ANN leg may still return explicitly labeled ANN-only results. Draft and deprecated atoms are excluded by default; pass include_drafts=true to include drafts (deprecated remain excluded). A query with no scoreable terms (e.g. \"AI\") can recover an eligible atom through an indexed exact-slug probe within the lexical stage's remaining deadline. The top-level `candidate_provenance` reports lexical state (`matched`, `exact_name`, `no_match`, `filtered`, `partial_timeout`, or `timed_out`), whether the returned set is an ANN fallback, and `terms_truncated` (true when any lexical pass drops terms beyond the shared 32-term allowance; full and decomposed passes draw from one budget before rarity, rowid, and eligibility probes). Every result carries `score_provenance` with lexical/ANN sources, embedding-rerank use, `s_over_s_plus_1` normalization, and `calibrated:false`. Scores are request-relative and squash-normalized to [0,1); absolute score is not a presence signal — use result rank together with provenance for presence/coverage checks. Atom results include `body_lines`, the aggregate line count of their stored sections (str::lines() semantics: a terminal newline adds no line, blank interior lines count; 0 for a sectionless atom); domain results and deadline-degraded rows report null, the latter alongside a `degraded` flag.",
visibility: Visibility::Verb,
category: VerbCategory::Assertive,
params: &[
ParamDef {
name: "query",
param_type: "string",
required: true,
description: "Search query text",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "type",
param_type: "string",
required: false,
description: "Filter: \"atom\" | \"domain\" (default: both)",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "include_drafts",
param_type: "boolean",
required: false,
description: "Include draft (unfinalized) atoms in results (default false). Has no effect when status= is set explicitly.",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "status",
param_type: "string",
required: false,
description: "Return only atoms with this exact status. Valid values: draft | reviewed | deprecated. Overrides include_drafts — when set, include_drafts has no effect.",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "exclude_status",
param_type: "string",
required: false,
description: "Exclude atoms with this exact status. Only used when status= is not set. Valid values: draft | reviewed | deprecated.",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "role",
param_type: "string",
required: false,
description: "Agent role hint prepended to query for scoring",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "limit",
param_type: "integer",
required: false,
description: "Max results (default 10, max 100)",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "min_score",
param_type: "number",
required: false,
description: "Minimum final-score threshold (default 0.0). Scores are request-relative and squash-normalized to [0,1), not calibrated presence signals; use rank together with candidate_provenance and score_provenance.",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "weights",
param_type: "object",
required: false,
description: "TF-IDF weight overrides: {w_name, w_tags, w_content, w_exact_name, w_bigram, expand_discount, coverage_alpha}",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "decompose",
param_type: "boolean",
required: false,
description: "Enable query decomposition (default false)",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "decompose_threshold",
param_type: "integer",
required: false,
description: "Min non-stop terms to trigger decomposition (default 4)",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "intersection_bonus",
param_type: "number",
required: false,
description: "Score multiplier for multi-sub-query hits (default 0.25)",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "rerank",
param_type: "boolean",
required: false,
description: "Enable embedding rerank (default true; set false to opt out; no-op if no embedder is configured)",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "rerank_alpha",
param_type: "number",
required: false,
description: "TF-IDF vs embedding blend weight (default 0.7 = TF-IDF dominant)",
resolution_mode: IdResolutionMode::NotApplicable,
},
],
},
HandlerDef {
name: "knowledge.suggest",
description: "Suggest relevant knowledge domains for a query. Draft and deprecated domain atoms are excluded by default (same quality default as knowledge.search). Each result carries {id, name, score, size, members} — `size` is the aggregate estimated-token cost of the domain's live member atom bodies, and `members` is their count. A present domain without live members has size 0 and members 0. The size uses the same unit as `knowledge.fold`'s `budget`, so results feed `knowledge.fold(candidates=...)` directly with no caller-side field construction. When ANN candidate retrieval is unavailable, the response sets `ann_unavailable: true` and reports `degraded.mode`: `no_match` when lexical/FTS retrieval found no candidates, `ann_candidates_degraded` when lexical/FTS candidates still received fresh embedding cosine reranking, or `lexical_only` when that fresh rerank did not run.",
visibility: Visibility::Verb,
category: VerbCategory::Assertive,
params: &[
ParamDef {
name: "query",
param_type: "string",
required: true,
description: "Orientation query text",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "role",
param_type: "string",
required: false,
description: "Agent role hint prepended to query for scoring",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "limit",
param_type: "integer",
required: false,
description: "Max domains (default 8, max 100)",
resolution_mode: IdResolutionMode::NotApplicable,
},
],
},
HandlerDef {
name: "knowledge.compose",
description: "Compose a budgeted markdown briefing from selected knowledge domains and atoms. The returned atoms/count describe atoms actually rendered in the briefing, not all reranked candidates.",
visibility: Visibility::Verb,
category: VerbCategory::Assertive,
params: &[
ParamDef {
name: "namespace",
param_type: "string",
required: false,
// MAINTENANCE, deliberately kept out of the description: this is the
// ADR-007 Rev 6 escape hatch.
description: "Exact-match read namespace override. When absent, compose uses the caller token's namespace. When present, atom, domain, section, KG-blend, and profile-weight reads use exactly this namespace; invalid values are rejected.",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "domain_ids",
param_type: "array of string",
required: false,
description: "Domain UUIDs or slugs whose member atoms should be included",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "atom_ids",
param_type: "array of string",
required: false,
description: "Atom UUIDs or slugs to include directly",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "query",
param_type: "string",
required: true,
description: "Query used to rerank selected atom bodies",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "blend_kg",
param_type: "boolean",
required: false,
description: "Blend relevant KG concept/document entities into the briefing as a supplementary \"Knowledge graph\" section (default true). Has no effect on atom_ids-only calls, which never blend.",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "auto_limit",
param_type: "integer",
required: false,
description: "Number of domains to auto-suggest from `query` when both domain_ids and atom_ids are empty (default 5, clamped 1-20). This caps suggested candidates before domains without live members are dropped, so auto-compose may compose fewer domains than auto_limit.",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "max_tokens",
param_type: "integer",
required: false,
description: "Output budget for the complete composed markdown (default 8000, clamped 500-100000; at most 4 UTF-8 bytes/token, including query, headings, sources, scores, domains, and blended entities). Oversized candidates are skipped so smaller later ones can fit.",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "explain",
param_type: "boolean",
required: false,
description: "Include per-section score breakdowns in the response (default false).",
resolution_mode: IdResolutionMode::NotApplicable,
},
],
},
// ── section tier ─────────────────────────────────────────────────────────
HandlerDef {
name: "knowledge.edit",
description: "Upsert sections for an atom without wiping other sections",
visibility: Visibility::Verb,
category: VerbCategory::Commissive,
params: &[
ParamDef {
name: "id",
param_type: "string",
required: true,
description: "Atom UUID or slug to edit sections for",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "sections",
param_type: "array of object",
required: true,
description: "Sections to upsert: [{section_type, content, heading?, sort_order?}]. \
section_type is a closed enum — valid values: overview | core_model | boundary_conditions | formalism | operational_guidance | examples | failure_modes | expert_lens. \
content must be ≥80 characters. Resubmitting the same content for an atom updates that section's stored section_type and heading.",
resolution_mode: IdResolutionMode::NotApplicable,
},
],
},
HandlerDef {
name: "knowledge.import",
description: "Validate and ingest atlas markdown with canonical-frontmatter or path identity",
visibility: Visibility::Verb,
category: VerbCategory::Commissive,
params: &[
ParamDef {
name: "path",
param_type: "string",
required: true,
description: "Filesystem path to a .md file or bounded directory tree",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "format",
param_type: "string",
required: false,
description: "Markdown format hint; only \"atlas_md\" supported (default)",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "chunk_strategy",
param_type: "string",
required: false,
description: "\"section\" (atom plus parsed section rows, default) or \"atom\" (post-frontmatter markdown body in one atom, no section rows)",
resolution_mode: IdResolutionMode::NotApplicable,
},
],
},
// ── section review tier ───────────────────────────────────────────────────
HandlerDef {
name: "knowledge.challenge",
description: "Mark a section as disputed and increment atom dispute_count",
visibility: Visibility::Verb,
category: VerbCategory::Commissive,
params: &[
ParamDef {
name: "atom_id",
param_type: "string",
required: true,
description: "Atom UUID or slug",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "section_type",
param_type: "string",
required: true,
description: "Section type to challenge",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "content_hash",
param_type: "string",
required: false,
description: "content_hash (from knowledge.edit) disambiguating which same-type section to challenge; required when more than one eligible section of section_type exists",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "reason",
param_type: "string",
required: false,
description: "Optional challenge reason",
resolution_mode: IdResolutionMode::NotApplicable,
},
],
},
HandlerDef {
name: "knowledge.adjudicate",
description: "Resolve a disputed section and decrement atom dispute_count",
visibility: Visibility::Verb,
category: VerbCategory::Commissive,
params: &[
ParamDef {
name: "atom_id",
param_type: "string",
required: true,
description: "Atom UUID or slug",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "section_type",
param_type: "string",
required: true,
description: "Section type to adjudicate",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "content_hash",
param_type: "string",
required: false,
description: "content_hash (from knowledge.edit) disambiguating which same-type disputed section to resolve; required when more than one disputed section of section_type exists",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "resolution",
param_type: "string",
required: true,
description: "\"accept\" (mark verified) or \"reject\" (mark reviewed)",
resolution_mode: IdResolutionMode::NotApplicable,
},
],
},
// ── concept tier (KG sugar) ───────────────────────────────────────────────
HandlerDef {
name: "knowledge.learn",
description: "Register a concept entity with optional domain and tags",
visibility: Visibility::Verb,
category: VerbCategory::Commissive,
params: &[
ParamDef {
name: "name",
param_type: "string",
required: false,
description: "Concept name. When omitted, auto-derived from `description`/`content` (truncated to the last word boundary <=60 chars); at least one of name or description/content must be non-empty.",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "description",
param_type: "string",
required: false,
description: "Optional concept description. Also accepted as `content` (alias) for UX consistency.",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "domain",
param_type: "string",
required: false,
description: "Optional domain tag (folded into properties.domain)",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "tags",
param_type: "array of string",
required: false,
description: "Optional tag list",
resolution_mode: IdResolutionMode::NotApplicable,
},
],
},
HandlerDef {
name: "knowledge.cite",
description: "Link a concept to the paper or source that introduced it",
visibility: Visibility::Verb,
category: VerbCategory::Commissive,
params: &[
ParamDef {
name: "concept_id",
param_type: "uuid",
required: true,
description: "Concept entity complete UUID or unique 8+ hex prefix. Prefix \
resolution searches the caller's primary namespace.",
resolution_mode: IdResolutionMode::PrefixScopedToPrimary,
},
ParamDef {
name: "source_id",
param_type: "uuid",
required: true,
description: "Source entity complete UUID or unique 8+ hex prefix; prefix \
resolution searches the caller's primary namespace. The source \
must be kind=document, kind=person, or kind=org (introduced_by \
edge rule).",
resolution_mode: IdResolutionMode::PrefixScopedToPrimary,
},
ParamDef {
name: "weight",
param_type: "number",
required: false,
description: "Edge weight; defaults to 1.0, clamped 0.0-1.0",
resolution_mode: IdResolutionMode::NotApplicable,
},
],
},
HandlerDef {
name: "knowledge.topic",
description: "List concepts filtered by domain or free-text query. With query, candidate_window_count counts hydrated, domain-filtered candidates before the final output limit, not corpus matches. Without query, total is the full matching visible concept count.",
visibility: Visibility::Verb,
category: VerbCategory::Assertive,
params: &[
ParamDef {
name: "domain",
param_type: "string",
required: false,
description: "Filter to concepts with this domain tag",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "query",
param_type: "string",
required: false,
description: "Free-text search across concept name + description",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "limit",
param_type: "integer",
required: false,
description: "Max results; defaults to 20, capped at 100",
resolution_mode: IdResolutionMode::NotApplicable,
},
],
},
// ── feedback tier ─────────────────────────────────────────────────────────
HandlerDef {
name: "knowledge.feedback",
description: "Record feedback on knowledge atoms/domains; optional section signals tune the selected profile or namespace prior. Knowledge event commits before profile learning; a later profile failure reports the committed event ID and unconfirmed profile outcome.",
visibility: Visibility::Verb,
category: VerbCategory::Commissive,
params: &[
ParamDef {
name: "section_signals", param_type: "object", required: false,
description: "Non-empty section_type to useful | not_useful | wrong map. At least signal or section_signals is required. Section learning requires an attributed caller; no scalar signal is invented.",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "target_id", param_type: "string", required: false,
description: "Live knowledge atom/domain UUID or unique undashed hex prefix (at least 8 characters). Required with signal; optional for section-only feedback. KG entity/note IDs and slugs are not feedback targets. Supplied IDs are always resolved and recorded.",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "signal", param_type: "string", required: false,
description: "Scalar judgment: useful | not_useful | wrong. Requires target_id; scalar-only feedback records the judgment without changing section weights.",
resolution_mode: IdResolutionMode::NotApplicable,
},
ParamDef {
name: "served_by_profile_id", param_type: "string", required: false,
description: "Explicit serving profile, ahead of pack configuration and actor/namespace knowledge_compose binding. Profile feedback requires an attributed caller. Omit all profile selectors to use namespace-local section state when no binding exists.",
resolution_mode: IdResolutionMode::NotApplicable,
},
],
},
];
#[cfg(test)]
mod tests {
use super::*;
fn find_handler(name: &str) -> &'static HandlerDef {
KNOWLEDGE_HANDLERS
.iter()
.find(|h| h.name == name)
.unwrap_or_else(|| panic!("handler {name:?} not found in KNOWLEDGE_HANDLERS"))
}
/// knowledge.edit sections param must document the closed section_type enum (8 values) and
/// the 80-character content minimum (#160).
#[test]
fn knowledge_edit_sections_documents_enum_and_content_minimum() {
let h = find_handler("knowledge.edit");
let sections = h
.params
.iter()
.find(|p| p.name == "sections")
.expect("knowledge.edit must have a sections param");
assert!(
sections.description.contains("80"),
"knowledge.edit sections description must document the 80-character content minimum"
);
// Every member of the closed enum is listed, and the retired names are not.
for name in khive_brain_core::SectionType::NAMES {
assert!(
sections.description.contains(name),
"knowledge.edit sections description must list '{name}' as a valid section_type"
);
}
for retired in khive_brain_core::SectionType::RETIRED_NAMES {
assert!(
!sections.description.contains(retired),
"knowledge.edit sections description must not list the retired '{retired}'"
);
}
// Verify the description calls out the closed-enum nature so callers know unrecognized
// values are rejected (not silently coerced).
assert!(
sections.description.contains("closed enum"),
"knowledge.edit sections description must state that section_type is a closed enum"
);
}
/// Parameter-parity guard (cross-model tooling evaluation, "compose budget
/// discoverability"): the top-level field names each handler's `#[derive(Deserialize)]`
/// params struct actually accepts, hand-kept in sync with
/// `src/knowledge/schema.rs` and `src/handlers.rs`. Every verb's entry here must be
/// exactly the set of top-level param names advertised in `KNOWLEDGE_HANDLERS` for
/// that verb (order-independent) -- so a field added to a params struct without a
/// matching `ParamDef` (or a stale `ParamDef` for a removed field) fails this test
/// instead of silently drifting from the actual accepted request shape.
///
/// Nested/child structs (e.g. `AtomInput` within `upsert_atoms.atoms`,
/// `FoldCandidate` within `fold.candidates`) are documented in prose inside the
/// parent `ParamDef.description` rather than as separate top-level entries here.
fn expected_params() -> &'static [(&'static str, &'static [&'static str])] {
&[
(
"knowledge.upsert_atoms",
&["atoms", "chunk_size", "dry_run"],
),
("knowledge.upsert_domains", &["domains"]),
("knowledge.get", &["id", "include_sections"]),
(
"knowledge.list",
&[
"type",
"limit",
"offset",
"after",
"fields",
"status",
"exclude_status",
],
),
("knowledge.delete_atoms", &["ids", "cascade"]),
("knowledge.stats", &[]),
("knowledge.eval_retrieval", &["query_set"]),
(
"knowledge.index",
&["ids", "batch_size", "insert_only", "rebuild_ann"],
),
(
"knowledge.fold",
&[
"candidates",
"budget",
"min_score",
"category_weights",
"diversity_bias",
"epistemic_weight",
],
),
(
"knowledge.search",
&[
"query",
"type",
"include_drafts",
"status",
"exclude_status",
"role",
"limit",
"min_score",
"weights",
"decompose",
"decompose_threshold",
"intersection_bonus",
"rerank",
"rerank_alpha",
],
),
("knowledge.suggest", &["query", "role", "limit"]),
(
"knowledge.compose",
&[
"namespace",
"domain_ids",
"atom_ids",
"query",
"blend_kg",
"auto_limit",
"max_tokens",
"explain",
],
),
("knowledge.edit", &["id", "sections"]),
("knowledge.import", &["path", "format", "chunk_strategy"]),
(
"knowledge.challenge",
&["atom_id", "section_type", "content_hash", "reason"],
),
(
"knowledge.adjudicate",
&["atom_id", "section_type", "content_hash", "resolution"],
),
(
"knowledge.learn",
&["name", "description", "domain", "tags"],
),
("knowledge.cite", &["concept_id", "source_id", "weight"]),
("knowledge.topic", &["domain", "query", "limit"]),
(
"knowledge.feedback",
&[
"section_signals",
"target_id",
"signal",
"served_by_profile_id",
],
),
]
}
#[test]
fn advertised_params_match_expected_deserialized_fields_for_every_verb() {
for (verb, expected) in expected_params() {
let h = find_handler(verb);
let mut advertised: Vec<&str> = h.params.iter().map(|p| p.name).collect();
let mut expected: Vec<&str> = expected.to_vec();
advertised.sort_unstable();
expected.sort_unstable();
assert_eq!(
advertised, expected,
"{verb}: advertised params {advertised:?} do not match the params \
struct's deserialized fields {expected:?} -- update either the \
`ParamDef`s in KNOWLEDGE_HANDLERS or the `expected_params()` table \
in this test (whichever is stale)"
);
}
}
/// Every verb declared in `KNOWLEDGE_HANDLERS` must have a parity row above --
/// otherwise a newly added verb could silently escape this guard.
#[test]
fn every_handler_has_a_parity_row() {
let covered: std::collections::HashSet<&str> =
expected_params().iter().map(|(name, _)| *name).collect();
for h in KNOWLEDGE_HANDLERS.iter() {
assert!(
covered.contains(h.name),
"{}: no entry in expected_params() -- add one so parameter drift \
on this verb cannot silently return",
h.name
);
}
}
}