Skip to content

[ADR-017] Pack Verb Registry, Wire Names, and Introspection #322

@ohdearquant

Description

@ohdearquant

Summary

Apply pack-prefixed wire names, visibility filtering, verb categories, collision errors, kind hook routing, and CLI/MCP introspection updates across built-in packs.

Source ADRs

  • F093 ADR-017 (CRIT): Registry comments and dispatch use "first registered pack wins" when multiple packs declare the same verb. (from audit-platform/e1/ADR-017.md)
  • F094 ADR-017 (CRIT): Tests assert duplicate create dispatch resolves to the first registered pack. (from audit-platform/e1/ADR-017.md)
  • F095 ADR-017 (MAJ): VerbRegistry stores only packs, gate, namespace, event store, and dispatch hook (from audit-platform/e1/ADR-017.md)
  • F096 ADR-017 (MAJ): find_kind_hook walks packs and returns the first owning pack hook. (from audit-platform/e1/ADR-017.md)
  • F097 ADR-017 (MAJ): KG_VERBS contains 11 entries and dispatch matches only create/get/list/update/delete/merge/search/link/neighbors/traverse/query. (from audit-platform/e1/ADR-017.md)
  • F098 ADR-018 (MAJ): VerbRegistryBuilder stores packs, one gate, default_namespace, event_store, and dispatch_hook, but no pack policy registry (from audit-platform/e3/ADR-018.md)
  • F099 ADR-018 (MAJ): The default Gate::impl_name returns the literal "Gate" for every implementation that does not override it. (from audit-platform/e3/ADR-018.md)
  • F118 ADR-023 (CRIT): MCP catalog is built from registry.all_verbs_with_names() with no visibility filtering (from audit-platform/e1/ADR-023.md)
  • F119 ADR-023 (CRIT): Memory registers internal pipeline entries as normal verbs: recall.embed, recall.candidates, recall.fuse, and recall.score. (from audit-platform/e1/ADR-023.md)
  • F120 ADR-023 (CRIT): GTD registers bare verbs assign, next, complete, tasks, and transition. (from audit-platform/e1/ADR-023.md)
  • F121 ADR-023 (CRIT): Memory registers bare verbs remember and recall, plus non-pack-prefixed dotted subhandlers. (from audit-platform/e1/ADR-023.md)
  • F122 ADR-023 (MAJ): KG exposes 11 verbs. (from audit-platform/e1/ADR-023.md)
  • F123 ADR-023 (CRIT): Duplicate verb names are resolved by first registered pack winning. (from audit-platform/e1/ADR-023.md)
  • F124 ADR-023 (MAJ): KindHook contains only prepare_create and after_create. (from audit-platform/e1/ADR-023.md)
  • F125 ADR-023 (MAJ): handle_list resolves kind and performs runtime listing directly (from audit-platform/e1/ADR-023.md)
  • F126 ADR-023 (MAJ): VerbInfo exposes only name and description (from audit-platform/e1/ADR-023.md)
  • F137 ADR-025 (MAJ): KG classifications are comments adjacent to VerbDef entries (from audit-platform/e1/ADR-025.md)
  • F138 ADR-025 (MAJ): GTD classifications are comments adjacent to VerbDef entries (from audit-platform/e1/ADR-025.md)
  • F139 ADR-025 (MAJ): Memory classifications are comments only; remember, recall, and recall pipeline handlers have no runtime category metadata. (from audit-platform/e1/ADR-025.md)
  • F140 ADR-025 (MAJ): Brain registers five VerbDef entries with no speech-act category metadata. (from audit-platform/e1/ADR-025.md)
  • F141 ADR-025 (CRIT): CLI introspection serializes VerbInfo { name, description } only. (from audit-platform/e1/ADR-025.md)
  • F142 ADR-025 (CRIT): MCP verb catalog maps registry entries to (pack, name, description) only. (from audit-platform/e1/ADR-025.md)
  • F144 ADR-025 (CRIT): GTD registers bare names, so the wire names are assign, next, complete, tasks, and transition. (from audit-platform/e1/ADR-025.md)
  • F145 ADR-025 (CRIT): Memory registers bare remember/recall and dotted recall.* entries without the memory. (from audit-platform/e1/ADR-025.md)

Files affected

  • crates/khive-runtime/src/pack.rs (2677 sampled LOC)
  • crates/khive-pack-kg/src/lib.rs (163 sampled LOC)
  • crates/khive-gate/src/lib.rs (539 sampled LOC)
  • crates/khive-mcp/src/server.rs (404 sampled LOC)
  • crates/khive-pack-memory/src/lib.rs (140 sampled LOC)
  • crates/khive-pack-gtd/src/lib.rs (166 sampled LOC)
  • crates/khive-pack-kg/src/handlers.rs (1216 sampled LOC)
  • crates/kkernel/src/pack_introspect.rs (153 sampled LOC)
  • crates/khive-pack-brain/src/lib.rs (424 sampled LOC)
  • crates/khive-pack-gtd/src/handlers.rs (593 sampled LOC)
  • crates/khive-pack-memory/src/handlers.rs (678 sampled LOC)
  • crates/khive-runtime/src/error.rs (125 sampled LOC)

Acceptance criteria

  • All source findings listed above are addressed exactly once in this cluster.
  • Public types, handlers, schema, and docs touched by the affected files agree on the ADR contract.
  • Regression tests cover happy path and edge cases for the changed public APIs or schema behavior.
  • cargo test -p khive-runtime -p khive-mcp -p kkernel -p khive-pack-kg -p khive-pack-gtd -p khive-pack-memory -p khive-pack-brain passes.
  • cargo clippy --workspace -- -D warnings passes.
  • make ci passes.

Dependencies

  • Depends on: #[ADR-001] Entity Kind and Type Contract
  • Depends on: #[ADR-002] Edge Ontology, Lifecycle, and Bulk Link Semantics
  • Depends on: #[ADR-004] Note Kind, Storage, and Curation Operations
  • Depends on: #[ADR-004] Event Observable and Provenance Model
  • Depends on: #[ADR-007] Namespace Token and Runtime API Migration
  • Depends on: #[ADR-003] Runtime Backend and Substrate Coordinator
  • Depends on: #[ADR-004] HandlerDef Pack Contract
  • Blocks: #[ADR-016] Request Execution Modes and Presentation Envelope
  • Blocks: #[ADR-023] Dynamic Pack Loading, Template, and Pack Binary Inclusion
  • Blocks: #[ADR-004] GTD Pack Schema Plan and Lifecycle Audit
  • Blocks: #[ADR-021] Memory Recall and Rerank Pipeline
  • Blocks: #[ADR-032] Brain Profile Orchestration
  • Blocks: #[ADR-025] Event-Sourced Proposals
  • Blocks: #[ADR-035] Import, Export, Remote Resolver, and Sync

LOC estimate

~760 lines added/240 removed; 12 existing affected file(s) sampled at 7278 current LOC via wc -l, plus 0 new/planned path(s).

Risk notes

  • Same-file dependencies must merge first; dependency list includes the exact overlapping paths.
  • Estimate exceeds the <=500 net target; keep implementation internally staged but preserve one merge cluster because the file surface is tightly coupled.
  • Contains CRIT findings; do not defer without owner approval.

Auto-generated by ADR alignment triage

Metadata

Metadata

Assignees

No one assigned

    Labels

    adr-alignmentADR v1 series alignment workplatformPlatform layer (ADR-016..030)

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions