khive-pack-knowledge 0.14.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
//! Static handler descriptor table for the knowledge pack (21 verbs + 1 subhandler).

use khive_types::{HandlerDef, IdResolutionMode, ParamDef, VerbCategory, Visibility};

const ROLE_PARAM: ParamDef = ParamDef {
    name: "role",
    param_type: "string",
    required: false,
    description: "Agent role hint prepended to query for scoring",
    resolution_mode: IdResolutionMode::NotApplicable,
};

const ATOM_ID_PARAM: ParamDef = ParamDef {
    name: "atom_id",
    param_type: "string",
    required: true,
    description: "Atom UUID or slug",
    resolution_mode: IdResolutionMode::NotApplicable,
};

/// 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; 22] = [
    // ── 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,
            },
            ROLE_PARAM,
            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,
            },
            ROLE_PARAM,
            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: &[
            ATOM_ID_PARAM,
            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: &[
            ATOM_ID_PARAM,
            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,
            },
        ],
    },
    HandlerDef {
        name: "knowledge.lint",
        description: "Inspect the caller-visible graph with thirteen built-in hygiene rules and complete pre-fix statistics. fix=true requests three guarded repair families with per-action committed/conflict/unsupported receipts; partial failures retain confirmed effects and typed settlement evidence. Corpus atoms and sections are separate from graph records. Classified Write, including inspection and stats-only.",
        visibility: Visibility::Verb,
        category: VerbCategory::Commissive,
        params: &[
            ParamDef {
                name: "rules", param_type: "array of string", required: false,
                description: "Omit for all thirteen built-ins, or a nonempty array of exact IDs: orphan-entity, dangling-edge, min-edge-density, direction-violation, missing-entity-type, missing-introduced-by, missing-implements, duplicate-name, superseded-not-marked, concept-no-parent, paper-missing-metadata, low-weight-edge, note-no-annotates. Repeated IDs run once. Sole stats-only returns exactly {stats} and cannot combine with fix=true. Nulls and unknown IDs refuse.",
                resolution_mode: IdResolutionMode::NotApplicable,
            },
            ParamDef {
                name: "fix", param_type: "boolean", required: false,
                description: "Default false. True prepares every reported fix candidate before any mutation, then checks each observed revision/witness in its owning database. Ordinary create/update/delete gates still apply. Adds fixes and summary.fixed (confirmed commits only); never automatically merges duplicate entities. Wrong types and null refuse.",
                resolution_mode: IdResolutionMode::NotApplicable,
            },
            ParamDef {
                name: "severity", param_type: "string", required: false,
                description: "Exact error | warn | info, default warn. Minimum reported severity; statistics always cover the full visible observation before fixes. Does not change rule severity. Invalid spellings, wrong types and null refuse.",
                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;