khive-pack-knowledge 0.8.0

Knowledge verb pack — lore corpus (atoms/domains), TF-IDF retrieval, concept registration
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
//! Static handler descriptor table for the knowledge pack (19 verbs + 1 subhandler).

use khive_types::{HandlerDef, 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] = [
    "CREATE TABLE IF NOT EXISTS knowledge_eval_runs (\
        id              TEXT PRIMARY KEY,\
        namespace       TEXT NOT NULL,\
        run_at          INTEGER NOT NULL,\
        query_set       TEXT NOT NULL,\
        total_queries   INTEGER NOT NULL,\
        precision_at_5  REAL NOT NULL,\
        recall_at_5     REAL NOT NULL,\
        mrr             REAL NOT NULL,\
        notes           TEXT\
    )",
    "CREATE INDEX IF NOT EXISTS idx_knowledge_eval_runs_ns_run_at \
        ON knowledge_eval_runs(namespace, run_at DESC)",
];

pub(crate) static KNOWLEDGE_HANDLERS: [HandlerDef; 20] = [
    // ── corpus tier ──────────────────────────────────────────────────────────
    HandlerDef {
        name: "knowledge.upsert_atoms",
        description: "Bulk insert or update knowledge atoms by slug",
        visibility: Visibility::Verb,
        category: VerbCategory::Commissive,
        params: &[
            ParamDef {
                name: "atoms",
                param_type: "array<object>",
                required: true,
                description: "List of atoms: {slug, name, content, tags?, properties?, finalized?}",
            },
            ParamDef {
                name: "chunk_size",
                param_type: "integer",
                required: false,
                description: "Per-chunk size for client-side chunking hint (max 5000)",
            },
        ],
    },
    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<object>",
            required: true,
            description: "List of domains: {slug, name, description?, tags?, members?}",
        }],
    },
    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.",
            },
            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.",
            },
        ],
    },
    HandlerDef {
        name: "knowledge.list",
        description: "Paginated listing of atoms or domains",
        visibility: Visibility::Verb,
        category: VerbCategory::Assertive,
        params: &[
            ParamDef {
                name: "type",
                param_type: "string",
                required: false,
                description: "Filter: \"atom\" | \"domain\" (default: atom)",
            },
            ParamDef {
                name: "limit",
                param_type: "integer",
                required: false,
                description: "Max results (default 20, max 500)",
            },
            ParamDef {
                name: "offset",
                param_type: "integer",
                required: false,
                description: "Pagination offset",
            },
            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.",
            },
            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.",
            },
        ],
    },
    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<string>",
                required: true,
                description: "Atom slugs or UUIDs to delete",
            },
            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.",
            },
        ],
    },
    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",
        }],
    },
    HandlerDef {
        name: "knowledge.index",
        description: "Backfill embeddings + FTS for atoms/domains",
        visibility: Visibility::Verb,
        category: VerbCategory::Commissive,
        params: &[
            ParamDef {
                name: "ids",
                param_type: "array<string>",
                required: false,
                description: "Atom slugs/IDs to index. Omit to index all.",
            },
            ParamDef {
                name: "batch_size",
                param_type: "integer",
                required: false,
                description: "Page size for whole-corpus indexing (default 500, max 1000)",
            },
            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.",
            },
            ParamDef {
                name: "rebuild_ann",
                param_type: "boolean",
                required: false,
                description: "Rebuild in-memory Vamana ANN index from embeddings (default false)",
            },
        ],
    },
    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<object>",
                required: true,
                description: "Scored items: {id, score, size, name?, content?, category?, information_gain?}. `knowledge.suggest`'s `results` feed this directly.",
            },
            ParamDef {
                name: "budget",
                param_type: "integer",
                required: true,
                description: "Token/size budget for the selected set",
            },
            ParamDef {
                name: "min_score",
                param_type: "number",
                required: false,
                description: "Minimum score threshold (default 0.0)",
            },
            ParamDef {
                name: "category_weights",
                param_type: "object",
                required: false,
                description: "Per-category score multipliers",
            },
            ParamDef {
                name: "diversity_bias",
                param_type: "number",
                required: false,
                description: "Selector diversity bias weight (default 0.0; must be finite)",
            },
            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)",
            },
        ],
    },
    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. Draft and deprecated atoms are excluded by default; pass include_drafts=true to include drafts (deprecated remain excluded). Scores are squash-normalized to [0,1); absolute score is not a presence signal — use result rank for presence/coverage checks.",
        visibility: Visibility::Verb,
        category: VerbCategory::Assertive,
        params: &[
            ParamDef {
                name: "query",
                param_type: "string",
                required: true,
                description: "Search query text",
            },
            ParamDef {
                name: "type",
                param_type: "string",
                required: false,
                description: "Filter: \"atom\" | \"domain\" (default: both)",
            },
            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.",
            },
            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.",
            },
            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.",
            },
            ParamDef {
                name: "role",
                param_type: "string",
                required: false,
                description: "Agent role hint prepended to query for scoring",
            },
            ParamDef {
                name: "limit",
                param_type: "integer",
                required: false,
                description: "Max results (default 10, max 100)",
            },
            ParamDef {
                name: "min_score",
                param_type: "number",
                required: false,
                description: "Minimum score threshold (default 0.0). Scores are squash-normalized to [0,1); absolute score is not a presence signal — use result rank for presence/coverage checks.",
            },
            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}",
            },
            ParamDef {
                name: "decompose",
                param_type: "boolean",
                required: false,
                description: "Enable query decomposition (default false)",
            },
            ParamDef {
                name: "decompose_threshold",
                param_type: "integer",
                required: false,
                description: "Min non-stop terms to trigger decomposition (default 4)",
            },
            ParamDef {
                name: "intersection_bonus",
                param_type: "number",
                required: false,
                description: "Score multiplier for multi-sub-query hits (default 0.25)",
            },
            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)",
            },
            ParamDef {
                name: "rerank_alpha",
                param_type: "number",
                required: false,
                description: "TF-IDF vs embedding blend weight (default 0.7 = TF-IDF dominant)",
            },
        ],
    },
    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} — `size` is the aggregate estimated-token cost of the domain's member atom bodies that compose expands, in 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",
            },
            ParamDef {
                name: "role",
                param_type: "string",
                required: false,
                description: "Agent role hint prepended to query for scoring",
            },
            ParamDef {
                name: "limit",
                param_type: "integer",
                required: false,
                description: "Max domains (default 8, max 100)",
            },
        ],
    },
    HandlerDef {
        name: "knowledge.compose",
        description: "Compose a markdown briefing from selected knowledge domains and atoms",
        visibility: Visibility::Verb,
        category: VerbCategory::Assertive,
        params: &[
            ParamDef {
                name: "namespace",
                param_type: "string",
                required: false,
                description: "Exact-match read namespace override (ADR-007 Rev 6 escape hatch). 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.",
            },
            ParamDef {
                name: "domain_ids",
                param_type: "array<string>",
                required: false,
                description: "Domain UUIDs or slugs whose member atoms should be included",
            },
            ParamDef {
                name: "atom_ids",
                param_type: "array<string>",
                required: false,
                description: "Atom UUIDs or slugs to include directly",
            },
            ParamDef {
                name: "query",
                param_type: "string",
                required: true,
                description: "Query used to rerank selected atom bodies",
            },
            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.",
            },
            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).",
            },
            ParamDef {
                name: "max_tokens",
                param_type: "integer",
                required: false,
                description: "Output token budget for the composed briefing (default 8000, clamped 500-100000; ~4 chars/token). Sections are trimmed to fit after scoring/selection.",
            },
            ParamDef {
                name: "explain",
                param_type: "boolean",
                required: false,
                description: "Include per-section score breakdowns in the response (default false).",
            },
        ],
    },
    // ── 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",
            },
            ParamDef {
                name: "sections",
                param_type: "array<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 | references | other. \
                    content must be ≥80 characters.",
            },
        ],
    },
    HandlerDef {
        name: "knowledge.import",
        description: "Validate and ingest atlas markdown file(s) with stable 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",
            },
            ParamDef {
                name: "format",
                param_type: "string",
                required: false,
                description: "Markdown format hint; only \"atlas_md\" supported (default)",
            },
            ParamDef {
                name: "chunk_strategy",
                param_type: "string",
                required: false,
                description: "\"section\" (atom plus parsed section rows, default) or \"atom\" (whole markdown in one atom, no section rows)",
            },
        ],
    },
    // ── 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",
            },
            ParamDef {
                name: "section_type",
                param_type: "string",
                required: true,
                description: "Section type to challenge",
            },
            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",
            },
            ParamDef {
                name: "reason",
                param_type: "string",
                required: false,
                description: "Optional challenge reason",
            },
        ],
    },
    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",
            },
            ParamDef {
                name: "section_type",
                param_type: "string",
                required: true,
                description: "Section type to adjudicate",
            },
            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",
            },
            ParamDef {
                name: "resolution",
                param_type: "string",
                required: true,
                description: "\"accept\" (mark verified) or \"reject\" (mark reviewed)",
            },
        ],
    },
    // ── 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.",
            },
            ParamDef {
                name: "description",
                param_type: "string",
                required: false,
                description: "Optional concept description. Also accepted as `content` (alias) for UX consistency.",
            },
            ParamDef {
                name: "domain",
                param_type: "string",
                required: false,
                description: "Optional domain tag (folded into properties.domain)",
            },
            ParamDef {
                name: "tags",
                param_type: "array<string>",
                required: false,
                description: "Optional tag list",
            },
        ],
    },
    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.",
            },
            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).",
            },
            ParamDef {
                name: "weight",
                param_type: "float",
                required: false,
                description: "Edge weight; defaults to 1.0, clamped 0.0-1.0",
            },
        ],
    },
    HandlerDef {
        name: "knowledge.topic",
        description: "List concepts filtered by domain or free-text query",
        visibility: Visibility::Verb,
        category: VerbCategory::Assertive,
        params: &[
            ParamDef {
                name: "domain",
                param_type: "string",
                required: false,
                description: "Filter to concepts with this domain tag",
            },
            ParamDef {
                name: "query",
                param_type: "string",
                required: false,
                description: "Free-text search across concept name + description",
            },
            ParamDef {
                name: "limit",
                param_type: "integer",
                required: false,
                description: "Max results; defaults to 20, capped at 100",
            },
        ],
    },
    // ── feedback tier ─────────────────────────────────────────────────────────
    HandlerDef {
        name: "knowledge.feedback",
        description: "Apply per-section feedback signals to update section posterior weights",
        visibility: Visibility::Verb,
        category: VerbCategory::Commissive,
        params: &[
            ParamDef {
                name: "section_signals",
                param_type: "object",
                required: true,
                description: "Map of section_type → signal string: {\"overview\": \"useful\", \"formalism\": \"not_useful\"}. Valid signals: useful | not_useful | wrong",
            },
            ParamDef {
                name: "target_id",
                param_type: "string",
                required: false,
                description: "Optional UUID of the atom or entity being rated. When provided alongside a configured brain profile, feedback is also forwarded to brain.feedback for profile-scoped section tracking.",
            },
        ],
    },
];

#[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 (10 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"
        );
        // Spot-check the first and last members of the closed enum.
        assert!(
            sections.description.contains("overview"),
            "knowledge.edit sections description must list 'overview' as a valid section_type"
        );
        assert!(
            sections.description.contains("other"),
            "knowledge.edit sections description must list 'other' as a valid section_type"
        );
        // 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"]),
            ("knowledge.upsert_domains", &["domains"]),
            ("knowledge.get", &["id", "include_sections"]),
            (
                "knowledge.list",
                &["type", "limit", "offset", "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"]),
        ]
    }

    #[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
            );
        }
    }
}