//! Static handler descriptor table for the knowledge pack (20 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; 21] = [
// ── 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.export",
description: "Export the selected namespace's live corpus rows as deterministic JSONL data with atom/domain/section counts. Includes domain mirror atoms, every lifecycle status and retired sections; excludes vectors and sections of deleted atoms. Does not write a file or export the KG graph.",
visibility: Visibility::Verb,
category: VerbCategory::Assertive,
params: &[ParamDef {
name: "format",
param_type: "string",
required: false,
description: "Output format: jsonl (the default and only supported value)",
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)]
#[path = "vocab_tests.rs"]
mod tests;