khive_runtime/pack/traits.rs
1use std::any::Any;
2use std::sync::Arc;
3
4use async_trait::async_trait;
5use khive_storage::EventView;
6use khive_types::NotePropertyPolicySpec;
7use serde_json::Value;
8
9use crate::context::ContextContributor;
10use crate::operations::LinkSpec;
11use crate::runtime::NamespaceToken;
12use crate::validation::ValidationRule;
13use crate::{KhiveRuntime, RuntimeError};
14
15use super::{
16 ChannelIngestCapability, EdgeEndpointRule, EntityTypeDef, HandlerDef, NoteEmbeddingPolicySpec,
17 NoteKindSpec, PackColumnAddition, VerbRegistry,
18};
19#[cfg(doc)]
20use super::{PackFactory, PackRegistry};
21
22/// Pack-auxiliary schema plan.
23///
24/// Declares `CREATE TABLE IF NOT EXISTS` statements for pack-owned tables that
25/// are NOT part of the core substrate schema (entities, notes, edges, events).
26/// Applied at boot via `StorageBackend::apply_pack_ddl_statements_with_columns`,
27/// together with [`PackRuntime::schema_column_additions`].
28///
29/// Core substrate tables evolve through versioned migrations. Pack schema is
30/// strictly for pack-auxiliary tables (e.g. GTD lifecycle audit, memory index).
31/// v1 pack schemas are non-versioned.
32#[derive(Debug, Default, Clone)]
33pub struct SchemaPlan {
34 /// Owning pack name.
35 pub pack: &'static str,
36 /// DDL statements applied idempotently at boot.
37 /// Each entry must be a self-contained `CREATE TABLE IF NOT EXISTS` or
38 /// similar idempotent statement.
39 pub statements: &'static [&'static str],
40}
41
42impl SchemaPlan {
43 /// Construct a `SchemaPlan` with no statements.
44 ///
45 /// Packs whose state lives entirely in the core substrate tables (entities,
46 /// notes, edges) use this as their `schema_plan()` return value.
47 pub const fn empty() -> Self {
48 Self {
49 pack: "",
50 statements: &[],
51 }
52 }
53
54 /// Returns `true` when the plan contains no DDL statements.
55 pub fn is_empty(&self) -> bool {
56 self.statements.is_empty()
57 }
58}
59
60/// Best-effort hook called after every successful verb dispatch.
61///
62/// The runtime supplies a synthetic [`EventView`] whose `event` describes the
63/// dispatch outcome and whose `observations` vector is currently empty. Loading
64/// persisted provenance observations belongs to an explicit caller or the
65/// deferred event-consumer contract; this hook does not provide it.
66#[async_trait]
67pub trait DispatchHook: Send + Sync {
68 /// Called with the dispatch-outcome event view after a successful pack dispatch.
69 ///
70 /// Errors are logged via `tracing::warn!` and never propagated to the
71 /// caller; the dispatch has already succeeded.
72 async fn on_dispatch(&self, view: &EventView);
73}
74
75/// Async dispatch trait for packs.
76///
77/// This is the object-safe behavioral counterpart to `khive_types::Pack`.
78/// `Pack` uses const associated items (not object-safe in Rust); this trait
79/// mirrors that metadata as methods and adds async dispatch.
80///
81/// Registration requires `P: Pack + PackRuntime` — the compiler enforces
82/// that every runtime pack also declares its vocabulary via `Pack`.
83#[async_trait]
84pub trait PackRuntime: Send + Sync {
85 /// Pack name — must equal `<Self as Pack>::NAME`.
86 fn name(&self) -> &str;
87
88 /// Optional instance-owned state for host work outside verb dispatch.
89 /// Return the same shared state used by this pack's handlers. The host
90 /// owns task startup and shutdown; this accessor must not start work.
91 fn host_state(&self) -> Option<Arc<dyn Any + Send + Sync>> {
92 None
93 }
94
95 /// Validate this pack instance's configuration before it can execute.
96 /// Metadata-only construction does not activate packs.
97 fn validate_config(&self) -> Result<(), RuntimeError> {
98 Ok(())
99 }
100
101 /// Note kinds this pack owns — must equal `<Self as Pack>::NOTE_KINDS`.
102 fn note_kinds(&self) -> &'static [&'static str];
103
104 /// Entity kinds this pack owns — must equal `<Self as Pack>::ENTITY_KINDS`.
105 fn entity_kinds(&self) -> &'static [&'static str];
106
107 /// Brain profile consumer kinds this pack requests — must equal
108 /// `<Self as Pack>::BRAIN_CONSUMER_KINDS`.
109 fn brain_consumer_kinds(&self) -> &'static [&'static str] {
110 &[]
111 }
112
113 /// Trusted in-process section feedback after the calling pack has validated
114 /// its own target. This is not a registered handler or a wire entry point.
115 async fn apply_profile_section_feedback(
116 &self,
117 _token: &NamespaceToken,
118 _profile_id: &str,
119 _section_signals: Value,
120 _target_attribution: Option<String>,
121 ) -> Result<Value, RuntimeError> {
122 Err(RuntimeError::InvalidInput(format!(
123 "pack {:?} does not support profile section feedback",
124 self.name()
125 )))
126 }
127
128 /// Handlers this pack registers — must equal `<Self as Pack>::HANDLERS`.
129 fn handlers(&self) -> &'static [HandlerDef];
130
131 /// Optional canonical input schema owned by the pack; ParamDefs remain available.
132 fn input_schema(&self, _verb: &str) -> Option<Value> {
133 None
134 }
135
136 /// Pack-extensible edge endpoint rules — must equal `<Self as Pack>::EDGE_RULES`.
137 /// Defaults to empty so existing packs that don't extend the edge contract
138 /// can ignore it.
139 fn edge_rules(&self) -> &'static [EdgeEndpointRule] {
140 &[]
141 }
142
143 /// Pack-extensible entity-type subtypes — must equal `<Self as Pack>::ENTITY_TYPES`.
144 /// Defaults to empty so existing packs that don't extend the entity_type
145 /// registry can ignore it.
146 fn entity_types(&self) -> &'static [EntityTypeDef] {
147 &[]
148 }
149
150 /// Pack names whose vocabulary this pack references.
151 /// Defaults to empty so existing packs compile without changes.
152 fn requires(&self) -> &'static [&'static str] {
153 &[]
154 }
155
156 /// NoteKindSpec declarations for note kinds this pack owns.
157 ///
158 /// Packs that introduce note kinds with explicit lifecycle semantics
159 /// declare the spec here. The runtime collects these for introspection
160 /// and future enforcement. Defaults to empty so existing packs compile
161 /// without changes.
162 fn note_kind_specs(&self) -> &'static [NoteKindSpec] {
163 &[]
164 }
165
166 /// Property-policy metadata for this pack's own note kinds.
167 ///
168 /// Mirror `Pack::NOTE_PROPERTY_POLICIES`. Boot validates and snapshots this
169 /// slice once, before activation. It does not install write enforcement.
170 fn note_property_policies(&self) -> &'static [NotePropertyPolicySpec] {
171 &[]
172 }
173
174 /// Per-kind write-time embedding policy; unlisted kinds use every model.
175 fn note_embedding_policies(&self) -> &'static [NoteEmbeddingPolicySpec] {
176 &[]
177 }
178
179 /// Optional per-kind hook for shared CRUD specialization.
180 ///
181 /// When a kind is owned by this pack (declared in `note_kinds()` or
182 /// `entity_kinds()`), returning `Some(hook)` opts that kind into
183 /// pack-specific behavior — defaults, derived properties, side-effect
184 /// edges — through the shared `create` path. Returning `None` keeps
185 /// the kind as plain storage with no specialization.
186 fn kind_hook(&self, _kind: &str) -> Option<Arc<dyn KindHook>> {
187 None
188 }
189
190 /// Optional context source, discovered without invoking contribution or dispatch.
191 ///
192 /// Return the instance-owned capability. Packs without context support keep the default.
193 /// See `docs/api/pack.md#context_contributor` for ownership and score contracts.
194 fn context_contributor(&self) -> Option<Arc<dyn ContextContributor>> {
195 None
196 }
197
198 /// Accept the trusted channel-ingest capability grant for this specific
199 /// pack instance.
200 ///
201 /// Called at most once per instance, immediately after this instance is
202 /// constructed via [`PackFactory::create_install`], and only for packs
203 /// whose name appears in `CHANNEL_INGEST_CAPABLE_PACKS`. Storing the
204 /// grant on `self` (rather than on the `&'static dyn PackFactory`, which
205 /// is a single process-wide singleton shared by every instance the
206 /// factory ever creates) makes the grant instance-bound: a `CommPack`
207 /// built outside [`PackRegistry::register_packs`] holds no capability
208 /// unless something calls this on that specific instance. Defaults to a
209 /// no-op so packs outside the allowlist compile without changes.
210 fn accept_channel_ingest_capability(&self, _capability: ChannelIngestCapability) {}
211
212 /// Pack-auxiliary schema.
213 ///
214 /// Returns DDL statements for pack-owned tables that are NOT part of the
215 /// core substrate schema. Statements are idempotent (`CREATE TABLE IF NOT
216 /// EXISTS`) so callers can apply them safely on every registration. Core
217 /// substrate tables evolve through versioned migrations; pack schema is
218 /// strictly pack-auxiliary.
219 ///
220 /// Defaults to an empty plan — packs that store everything in the core
221 /// substrate tables (entities, notes, edges, events) return this default.
222 ///
223 /// Plans are aggregated via [`VerbRegistry::all_schema_plans`] and applied
224 /// at startup via `KhiveMcpServer::with_packs`. Packs that need their
225 /// schema present (e.g. GTD) also self-bootstrap lazily on first call for
226 /// robustness in test contexts that create fresh in-memory databases.
227 fn schema_plan(&self) -> SchemaPlan {
228 SchemaPlan::empty()
229 }
230
231 /// Nullable-column upgrades for this pack's auxiliary tables.
232 ///
233 /// Must equal `Pack::SCHEMA_COLUMN_ADDITIONS`. The backend validates and
234 /// adds missing columns on existing tables before applying the full schema
235 /// plan, then validates every declared column. Both steps share the plan's
236 /// transaction. Defaults to empty for packs with no auxiliary upgrades.
237 fn schema_column_additions(&self) -> &'static [PackColumnAddition] {
238 &[]
239 }
240
241 /// Domain-specific validation rules contributed by this pack.
242 ///
243 /// Rule IDs MUST follow the `<pack>/<rule-id>` namespace convention.
244 /// Built-in rules (no pack prefix) are reserved for the `khive-runtime`
245 /// validation infrastructure.
246 ///
247 /// Defaults to empty — packs with no domain-specific rules return `&[]`.
248 fn validation_rules(&self) -> &'static [ValidationRule] {
249 &[]
250 }
251
252 /// Register custom embedding providers with the runtime. Called during pack
253 /// initialisation, before the first verb dispatch, so `KhiveRuntime::embedder(name)`
254 /// resolves provider names declared here. Default no-op — packs that only use
255 /// built-in lattice models do not need to override this.
256 /// See `docs/api/pack.md#register_embedders` for a usage example.
257 fn register_embedders(&self, _runtime: &KhiveRuntime) {}
258
259 /// Install a pack-owned entity-type validator on the runtime, called during pack
260 /// initialisation (after the registry is built, before the first dispatch) so
261 /// `create_many`/`create_entity` reject unregistered `entity_type` values at the
262 /// runtime layer. Default no-op leaves the validator absent (skip-when-None).
263 /// See `docs/api/pack.md#register_entity_type_validator` for the two-hook compatibility contract.
264 fn register_entity_type_validator(&self, _runtime: &KhiveRuntime) {}
265
266 /// Install a pack-owned entity-type validator that also receives the boot-time
267 /// composed set of every loaded pack's `ENTITY_TYPES` ([`VerbRegistry::all_entity_types`]).
268 /// Defaults to calling [`register_entity_type_validator`](Self::register_entity_type_validator)
269 /// with just the runtime. `call_register_entity_type_validators` calls this hook, not
270 /// the simpler one — override this to receive the composed vocabulary.
271 /// See `docs/api/pack.md#register_entity_type_validator` for the two-hook compatibility contract.
272 fn register_entity_type_validator_with_types(
273 &self,
274 runtime: &KhiveRuntime,
275 _pack_entity_types: &[EntityTypeDef],
276 ) {
277 self.register_entity_type_validator(runtime);
278 }
279
280 /// Install a pack-owned note-mutation hook on the runtime, called during pack
281 /// initialisation with the same timing as `register_entity_type_validator`. Packs
282 /// that cache derived state keyed by note content (e.g. `khive-pack-memory`'s warm
283 /// ANN index) override this to install a hook via
284 /// `KhiveRuntime::install_note_mutation_hook`. Default no-op leaves the hook absent.
285 /// See `docs/api/pack.md#register_note_mutation_hook` for cross-pack notification rationale.
286 fn register_note_mutation_hook(&self, _runtime: &KhiveRuntime) {}
287
288 /// Install a backend-matched note-search ANN candidate source. The
289 /// memory pack supplies it after registration; packs without a matching
290 /// graph leave the runtime's exact vector-store route in place.
291 fn register_note_search_ann_provider(&self, _runtime: &KhiveRuntime) {}
292
293 /// Install a note-write validator on the runtime, called at pack
294 /// initialisation with the same timing as `register_note_mutation_hook`.
295 ///
296 /// A pack owning a note kind whose properties carry identity that the
297 /// runtime can derive from the authorization token implements this and
298 /// calls `KhiveRuntime::install_note_write_validator`, so the identity is
299 /// derived at every note-write site rather than trusted from caller input
300 /// on the write paths that reach no pack verb. Default no-op leaves the
301 /// slot absent. The slot holds one validator, so an implementation must
302 /// return properties for kinds it does not own unchanged.
303 fn register_note_write_validator(&self, _runtime: &KhiveRuntime) {}
304
305 /// Warm up any in-memory state from persisted snapshots (optional). Called after
306 /// all packs are registered but before serving the first request. Must be
307 /// idempotent and infallible — errors are logged internally, never propagated.
308 async fn warm(&self) {}
309
310 /// Names of all embedding models registered on this pack's underlying runtime
311 /// handle. Defaults to empty — only packs that own embedding-bearing verbs
312 /// (kg, memory) need to override this.
313 /// See `docs/api/pack.md#registered_embedding_model_names` for the ADR-103 consumer.
314 fn registered_embedding_model_names(&self) -> Vec<String> {
315 Vec::new()
316 }
317
318 fn mounted_namespace(&self) -> Option<&str> {
319 None
320 }
321
322 /// Advisory owned catalog only: no storage, process, gate, or audit work.
323 fn mounted_catalog_snapshot(&self) -> Vec<crate::mounted_verb::MountedVerb> {
324 Vec::new()
325 }
326
327 async fn mounted_catalog(&self) -> Result<Vec<crate::mounted_verb::MountedVerb>, RuntimeError> {
328 Ok(Vec::new())
329 }
330
331 async fn dispatch_mounted(
332 &self,
333 _definition: &crate::mounted_verb::MountedVerb,
334 verb: &str,
335 params: Value,
336 registry: &VerbRegistry,
337 token: &NamespaceToken,
338 ) -> Result<Value, RuntimeError> {
339 self.dispatch(verb, params, registry, token).await
340 }
341
342 /// Typed note-search interception. Packs without the feature fail closed.
343 async fn dispatch_search_intercepted(
344 &self,
345 _params: serde_json::Value,
346 _registry: &crate::pack::VerbRegistry,
347 _token: &crate::NamespaceToken,
348 ) -> Result<
349 crate::pack::InterceptedDispatchResult<
350 Option<(khive_storage::note::NoteStatusSelector, u64)>,
351 >,
352 crate::RuntimeError,
353 > {
354 Err(crate::RuntimeError::Internal(
355 "registered search owner does not support intercepted search".into(),
356 ))
357 }
358
359 /// Dispatch a verb call. Returns serialized JSON response.
360 ///
361 /// The `registry` parameter gives the handler access to the merged
362 /// vocabulary and kind hooks across all loaded packs.
363 /// The `token` is an authorized namespace token minted by the dispatch
364 /// boundary after gate authorization — handlers must use it directly.
365 async fn dispatch(
366 &self,
367 verb: &str,
368 params: Value,
369 registry: &VerbRegistry,
370 token: &NamespaceToken,
371 ) -> Result<Value, RuntimeError>;
372}
373
374/// Per-kind specialization for shared CRUD.
375///
376/// Packs implement `KindHook` for kinds they own that need:
377/// - **Defaults** filled into create args (e.g. `status="inbox"` for tasks)
378/// - **Derived properties** computed from args (e.g. salience from priority)
379/// - **Side-effect writes** after the storage commit (e.g. `depends_on` edges)
380/// - **Cross-pack validation** before shared CRUD mutates an owned kind
381///
382/// Hooks are stateless from the framework's perspective — they receive the
383/// runtime and the current mutation inputs as method parameters. The pack
384/// registers them via [`PackRuntime::kind_hook`].
385///
386/// Lifecycle verbs (e.g. gtd's `complete`, `transition`) remain pack-owned
387/// verbs. Shared `create`, note `update`, entity `update`, and `link` calls
388/// flow through this trait when an endpoint kind has an owning pack hook.
389///
390/// A hook that still overrides the removed sequencing method does not compile, which is the point
391/// of the move: an implementor cannot replace the validator by replacing the sequence, because
392/// there is no sequence on this trait to replace.
393///
394/// ```compile_fail
395/// use async_trait::async_trait;
396/// use khive_runtime::{KhiveRuntime, KindHook, NamespaceToken, RuntimeError};
397/// use serde_json::Value;
398///
399/// #[derive(Debug)]
400/// struct Sequencing;
401///
402/// #[async_trait]
403/// impl KindHook for Sequencing {
404/// async fn prepare_create(
405/// &self,
406/// _runtime: &KhiveRuntime,
407/// _args: &mut Value,
408/// ) -> Result<(), RuntimeError> {
409/// Ok(())
410/// }
411///
412/// async fn after_create(
413/// &self,
414/// _runtime: &KhiveRuntime,
415/// _id: uuid::Uuid,
416/// _args: &Value,
417/// ) -> Result<(), RuntimeError> {
418/// Ok(())
419/// }
420///
421/// async fn prepare_note_update(
422/// &self,
423/// _runtime: &KhiveRuntime,
424/// _token: &NamespaceToken,
425/// _note: &khive_storage::Note,
426/// _args: &mut Value,
427/// ) -> Result<(), RuntimeError> {
428/// Ok(())
429/// }
430/// }
431/// ```
432///
433/// The companion below is the control, and it is what makes the arm above mean anything: a
434/// `compile_fail` doctest passes when the code fails to compile for ANY reason, including a stale
435/// import or a renamed type. This one is structurally identical and overrides the two halves a pack
436/// is meant to implement, so it must compile — if it stops compiling, the arm above has stopped
437/// testing the method and is passing on the scaffolding instead.
438///
439/// ```
440/// use async_trait::async_trait;
441/// use khive_runtime::{KhiveRuntime, KindHook, NamespaceToken, RuntimeError};
442/// use serde_json::Value;
443///
444/// #[derive(Debug)]
445/// struct Halves;
446///
447/// #[async_trait]
448/// impl KindHook for Halves {
449/// async fn prepare_create(
450/// &self,
451/// _runtime: &KhiveRuntime,
452/// _args: &mut Value,
453/// ) -> Result<(), RuntimeError> {
454/// Ok(())
455/// }
456///
457/// async fn after_create(
458/// &self,
459/// _runtime: &KhiveRuntime,
460/// _id: uuid::Uuid,
461/// _args: &Value,
462/// ) -> Result<(), RuntimeError> {
463/// Ok(())
464/// }
465///
466/// async fn normalize_note_update(
467/// &self,
468/// _runtime: &KhiveRuntime,
469/// _token: &NamespaceToken,
470/// _note: &khive_storage::Note,
471/// _args: &mut Value,
472/// ) -> Result<(), RuntimeError> {
473/// Ok(())
474/// }
475///
476/// async fn validate_note_update(
477/// &self,
478/// _runtime: &KhiveRuntime,
479/// _token: &NamespaceToken,
480/// _note: &khive_storage::Note,
481/// _properties: Option<&Value>,
482/// ) -> Result<(), RuntimeError> {
483/// Ok(())
484/// }
485/// }
486/// ```
487#[async_trait]
488pub trait KindHook: Send + Sync + std::fmt::Debug {
489 /// Mutate args before the storage write. Fill defaults, normalize values,
490 /// rearrange user-facing fields into the storage shape expected by the
491 /// shared CRUD handler.
492 ///
493 /// Returning an error aborts the create call (no storage write happens).
494 async fn prepare_create(
495 &self,
496 runtime: &KhiveRuntime,
497 args: &mut Value,
498 ) -> Result<(), RuntimeError>;
499
500 /// Fire side effects after a successful storage write — graph edges,
501 /// derived observations, etc. The newly created record's UUID is passed
502 /// so the hook can attach metadata referencing it.
503 ///
504 /// Errors here are **logged but not propagated** — the storage write has
505 /// already succeeded; failing the call would mislead the caller.
506 /// Implementations should `tracing::warn!` and return `Ok(())` for
507 /// best-effort side effects. The default does nothing.
508 async fn after_create(
509 &self,
510 _runtime: &KhiveRuntime,
511 _id: uuid::Uuid,
512 _args: &Value,
513 ) -> Result<(), RuntimeError> {
514 Ok(())
515 }
516
517 /// Validate an approved AddEntity draft before preparing domain writes.
518 /// The draft kind is canonical.
519 /// This must not mutate storage or normalize the approved draft. The default
520 /// accepts it. This separate seam never invokes shared-create lifecycle
521 /// hooks and does not apply to AddNote; see `validate_proposal_note` below
522 /// for that route.
523 fn validate_proposal_entity(
524 &self,
525 _entity: &khive_types::EntityDraft,
526 ) -> Result<(), RuntimeError> {
527 Ok(())
528 }
529
530 /// Validate an `AddNote` draft on the proposal-note route, analogous to
531 /// [`Self::validate_proposal_entity`] but for notes. The kg pack's
532 /// proposal route calls this against the same immutable changeset at two
533 /// points: once when a new `propose` call is accepted, and again when an
534 /// approved proposal is applied, so a kind that refuses shared creation
535 /// is not bypassed by proposing the same creation instead. The draft's
536 /// kind is the owning pack's canonical spelling. This must not mutate
537 /// storage or normalize the draft; it only accepts or refuses. The
538 /// default accepts it.
539 fn validate_proposal_note(&self, _note: &khive_types::NoteDraft) -> Result<(), RuntimeError> {
540 Ok(())
541 }
542
543 /// Normalize caller-facing note-update fields before validation runs.
544 ///
545 /// Override this when a kind-owning pack's caller-facing note fields
546 /// mirror owned properties and must be changed together (for example, a
547 /// task's searchable `content` and `properties.description`). Validation
548 /// is not this method's job: the registry runs
549 /// [`Self::validate_note_update`] after this method returns, regardless of
550 /// what this method did. The default does nothing.
551 async fn normalize_note_update(
552 &self,
553 _runtime: &KhiveRuntime,
554 _token: &NamespaceToken,
555 _note: &khive_storage::Note,
556 _args: &mut Value,
557 ) -> Result<(), RuntimeError> {
558 Ok(())
559 }
560
561 /// Validate a shared note-property update before storage is mutated.
562 ///
563 /// The default accepts the update. Kind-owning packs override this when a
564 /// property has invariants that generic CRUD cannot know about (for
565 /// example, GTD task dependency acyclicity). This always runs after
566 /// [`Self::normalize_note_update`], because
567 /// [`VerbRegistry::prepare_note_update_policy`] calls them in that order.
568 async fn validate_note_update(
569 &self,
570 _runtime: &KhiveRuntime,
571 _token: &NamespaceToken,
572 _note: &khive_storage::Note,
573 _properties: Option<&Value>,
574 ) -> Result<(), RuntimeError> {
575 Ok(())
576 }
577
578 /// Describe graph changes coupled to a validated note patch, without writing.
579 ///
580 /// The dispatcher calls this only after normalization, kind validation, and
581 /// preparation of the note's guarded write. The runtime prepares these typed
582 /// effects and commits them with that write in one atomic unit. Implementors
583 /// must derive effects from this exact snapshot and patch; omitted or unchanged
584 /// owned fields should return no effects. This is not an after-update hook.
585 async fn note_update_effects(
586 &self,
587 _runtime: &KhiveRuntime,
588 _token: &NamespaceToken,
589 _note: &khive_storage::Note,
590 _patch: &crate::curation::NotePatch,
591 ) -> Result<Vec<NoteUpdateEffect>, RuntimeError> {
592 Ok(Vec::new())
593 }
594
595 /// Optional top-level properties whose explicit null update deletes the
596 /// stored key after the shared merge. Omission still preserves the key.
597 /// The default changes no property semantics. This policy is returned only
598 /// after normalization and validation have accepted the update.
599 fn note_update_null_clearing_properties(&self) -> &'static [&'static str] {
600 &[]
601 }
602
603 /// Validate a shared entity-property update before storage is mutated.
604 ///
605 /// Runs after the caller's patch has been merged into the entity's
606 /// stored properties, so `properties` reflects the resulting record
607 /// rather than the raw patch — the invariant this validates (e.g. "a
608 /// required key must be present and typed") is a claim about the
609 /// record, not about what one caller happened to send. This is
610 /// deliberately NOT a re-run of `prepare_create`: a `prepare_create`
611 /// body may also enforce create-shape requirements (an argument the
612 /// caller must supply at create time) that a partial update
613 /// legitimately omits, and re-running it would reject valid updates
614 /// with an error message written for create.
615 ///
616 /// The default accepts the update. Kind-owning packs override this when
617 /// a `prepare_create` invariant must also hold after a generic
618 /// `update`, sharing one predicate between both methods the way
619 /// [`validate_note_update`](Self::validate_note_update)'s implementors
620 /// already do for notes.
621 async fn validate_entity_update(
622 &self,
623 _runtime: &KhiveRuntime,
624 _token: &NamespaceToken,
625 _entity: &khive_storage::Entity,
626 _properties: Option<&Value>,
627 ) -> Result<(), RuntimeError> {
628 Ok(())
629 }
630
631 /// Validate one or more shared graph links before any edge is written.
632 ///
633 /// A batch is supplied as a unit so a hook can reject a cycle formed only
634 /// by the proposed edges. The default accepts every link.
635 async fn validate_links(
636 &self,
637 _runtime: &KhiveRuntime,
638 _token: &NamespaceToken,
639 _links: &[crate::LinkSpec],
640 ) -> Result<(), RuntimeError> {
641 Ok(())
642 }
643}
644
645/// A kind-owned graph mutation committed with its note update. SQL and deferred
646/// callbacks are deliberately not part of this interface.
647#[derive(Clone, Debug)]
648pub enum NoteUpdateEffect {
649 /// Create or explicitly resurrect an outgoing edge using normal link guards.
650 Link(LinkSpec),
651 /// Soft-delete one existing outgoing edge by ID, guarded by this snapshot.
652 DeleteEdge(khive_storage::types::Edge),
653 /// Preserve a live outgoing edge and assert its identity and endpoints at
654 /// commit time without changing its ID, timestamps, weight, or metadata.
655 AssertLink(khive_storage::types::Edge),
656}
657
658/// Optional sub-trait for packs that own private SQL tables and issue UUIDs
659/// that must be reachable through the generic `get(id)` and `delete(id)` verbs.
660///
661/// Implementing both methods is required — the sub-trait bundles them atomically
662/// so partial implementation is a compile-time error, not a runtime surprise.
663/// Packs whose records live in the shared entity/note substrate (gtd, memory)
664/// do not implement this sub-trait.
665#[async_trait]
666pub trait PackByIdResolver: Send + Sync {
667 /// Attempt to resolve a live (non-deleted) UUID owned by this pack's private tables.
668 ///
669 /// Returns `Some(Resolved::PackRecord { ... })` if this pack owns the UUID,
670 /// `None` if it does not (the caller continues to the next resolver),
671 /// or `Err(...)` on a storage error.
672 ///
673 /// Must query domain-authoritative tables before mirror tables.
674 /// Must NOT filter by namespace. UUID v4 is globally unique; by-ID
675 /// resolution is namespace-blind per ADR-007.
676 async fn resolve_by_id(
677 &self,
678 id: uuid::Uuid,
679 ) -> Result<Option<crate::Resolved>, crate::RuntimeError>;
680
681 /// Attempt to resolve a UUID including already-soft-deleted records.
682 ///
683 /// Used by the hard-delete path. Default delegates to `resolve_by_id`;
684 /// packs with `deleted_at` columns override this to query without the filter.
685 async fn resolve_by_id_including_deleted(
686 &self,
687 id: uuid::Uuid,
688 ) -> Result<Option<crate::Resolved>, crate::RuntimeError> {
689 self.resolve_by_id(id).await
690 }
691
692 /// Delete a record owned by this pack's private tables.
693 ///
694 /// `hard` mirrors the `delete` verb's `hard?` argument.
695 /// Default behavior for packs with a `deleted_at` column MUST be soft-delete;
696 /// `hard=true` performs permanent removal.
697 ///
698 /// Returns `Ok(Value)` with a `{ deleted: true, id, kind, hard }` body on success.
699 /// Returns `Err(RuntimeError::NotFound(...))` if the record does not exist.
700 async fn delete_by_id(
701 &self,
702 id: uuid::Uuid,
703 hard: bool,
704 ) -> Result<serde_json::Value, crate::RuntimeError>;
705
706 /// Verbs that change this pack's private records, named as examples when
707 /// a generic verb refuses one of them (ADR-061 Amendment 1).
708 ///
709 /// The refusal names the owning pack either way. A pack that returns
710 /// nothing is named without examples rather than borrowing another pack's.
711 fn private_record_verbs(&self) -> &'static [&'static str] {
712 &[]
713 }
714}