khive_types/

pack.rs

//! Pack trait — the declarative composition unit for khive.
//!
//! A pack declares vocabulary (note kinds, entity kinds, brain consumer
//! kinds), verbs, and edge endpoint rules. This is purely static metadata —
//! no I/O, no async.
//! Runtime dispatch lives in `khive-runtime` (`PackRuntime` trait +
//! `VerbRegistry`).
//!
//! This trait lives in khive-types (no_std, zero deps) so downstream crates
//! can reference pack metadata without pulling in the full runtime.

use crate::edge::EdgeRelation;
use crate::entity_type::EntityTypeDef;

/// Argument names owned by the outer request envelope rather than verb handlers.
///
/// Handler metadata must not advertise these names because every request parser rejects them
/// before pack dispatch. Keeping this list in the shared type crate lets both request parsing and
/// registry construction enforce one exact contract.
pub const RESERVED_ENVELOPE_ARGS: &[&str] = &["presentation", "presentation_per_op"];

/// Tag marking a `tool` pack registry object.
///
/// The value is on-disk data on every row the tool registry has ever minted,
/// so it is not free to change.
pub const TOOL_REGISTRY_TAG: &str = "tool-registry";

/// Tags whose presence makes an entity a pack's registry row.
///
/// Such a row is not ordinary metadata: its fields are policy inputs. The
/// tool registry's `source` names the binary a granted tool name resolves to,
/// and `side_effect` is read at run time and handed to the policy decision, so
/// a caller who can patch the row can change what a granted name does without
/// registering anything. The generic entity verbs therefore refuse to write a
/// row carrying one of these tags, including a patch that would remove the tag
/// itself, and the owning pack's verbs are the only writer.
///
/// This is a list rather than a field allow-list on purpose: a list of
/// protected properties goes stale the first time a pack adds a
/// capability-bearing property, which is exactly how `side_effect` was missed.
pub const PACK_REGISTRY_TAGS: &[&str] = &[TOOL_REGISTRY_TAG];

/// Visibility tier for a handler.
///
/// `Verb` entries appear on the MCP wire and are invokable by agents.
/// `Subhandler` entries are internal — callable by the operator via CLI
/// but not surfaced as top-level MCP verbs.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Visibility {
    /// Externally invokable via MCP `request` tool.
    Verb,
    /// Internal — operator-only via `kkernel exec '<pack>.<handler>(...)'`.
    Subhandler,
}

/// Illocutionary force classification for a verb handler.
///
/// Follows Searle's five speech-act categories (1976). Every `Visibility::Verb`
/// handler in the MCP surface MUST carry a category. `Subhandler` entries may
/// use the category of their parent verb or `Assertive` as a sensible default.
///
/// The category is a documentation / introspection tag. It is NOT used for
/// permission checking. It is one input — never the sole proof — to two
/// narrow, sanctioned runtime decisions, both in `khive-runtime`'s
/// `VerbRegistry`:
/// - `admission_degrade_safe` treats `Assertive` as a necessary condition
///   for letting a dispatch's own audit row degrade under transient
///   admission pressure, combined with an explicit per-verb allowlist.
/// - `is_retry_safe_after_frame_omission` treats `Assertive` as a necessary
///   condition for telling a caller that a response lost to the MCP
///   daemon's frame budget is safe to re-issue, combined with an explicit
///   exclusion list.
///
/// Both combine the category with an audited list rather than trusting it
/// alone, because several `Assertive` handlers schedule their own persisted
/// or accounting-bearing side effect on every dispatch (`memory.recall`'s
/// serve ledger, `search`'s `SearchExecuted` telemetry) that the speech-act
/// classification cannot see.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum VerbCategory {
    /// Speaker represents a state of affairs — retrieves and presents facts.
    /// Examples: `get`, `list`, `search`, `recall`.
    Assertive,
    /// Speaker attempts to get the hearer to do something.
    /// Examples: `assign`, `transition`.
    Directive,
    /// Speaker commits to a persistent change.
    /// Examples: `create`, `remember`, `link`, `send`.
    Commissive,
    /// Speaker changes institutional status by fiat.
    /// Examples: `update`, `delete`, `merge`, `complete`.
    Declaration,
    // `Expressive` is intentionally absent — no verb currently uses it.
}

/// How a `uuid` or `array of uuid` parameter resolves a caller-supplied
/// identifier — full UUID and short hex-prefix acceptance, and whether
/// either form is checked against a namespace. This is a property of the
/// handler's own resolution code, declared explicitly per parameter so
/// `VerbRegistry::describe_verb`'s rendered contract can never drift from
/// what the handler actually does (see khive-runtime's `pack.rs`
/// `IdResolutionMode` rendering table for the exact wording per variant).
///
/// Every variant here must correspond to a resolver function that actually
/// exists in the codebase — this is not a place to guess. When a new `uuid`
/// parameter is added, its handler must be read to determine which existing
/// variant matches (or whether a new one is needed); the parameter name
/// alone never determines the mode.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
pub enum IdResolutionMode {
    /// Not a UUID-typed identifier parameter — no resolver contract applies.
    #[default]
    NotApplicable,
    /// ADR-007 Rev 6 by-ID contract: a full UUID and a short hex prefix both
    /// resolve with no namespace predicate at all. The Gate, not
    /// storage-layer filtering, is the authorization seam. Used by `get`,
    /// `update`, `delete`, `merge`, `link`'s endpoint parameters, GTD's
    /// lifecycle `id` parameters, and brain's feedback `target_id`.
    UnscopedById,
    /// A full UUID resolves as given, with no namespace check performed by
    /// the resolver. A short hex prefix is resolved by searching only the
    /// caller's primary namespace. Used by graph-read anchors
    /// (`neighbors`/`traverse`) and citation targets.
    PrefixScopedToPrimary,
    /// Both a full UUID and a short hex prefix are validated against the
    /// caller's primary namespace: a record that exists but belongs to a
    /// different namespace resolves as not found.
    FullAndPrefixScopedToPrimary,
    /// Only a full UUID is accepted — a short hex prefix is rejected
    /// outright — and the UUID is validated against the caller's own
    /// (primary) namespace.
    FullUuidOnlyScopedToPrimary,
    /// Only a full UUID is accepted — a short hex prefix is rejected
    /// outright — and no namespace check is performed by the resolver
    /// itself (any namespace scoping comes from the enclosing operation,
    /// not from this parameter).
    UnscopedFullUuidOnly,
    /// `list.target_id`: edge lists resolve full UUIDs as given and prefixes
    /// or entity names in the primary namespace; event lists accept only an
    /// exact full subject UUID, with visibility applied to event rows.
    EdgeOrEventTarget,
}

/// Parameter type for `help=true` schema envelopes.
///
/// Declares the name, type hint, required flag, and one-line description for
/// a single verb parameter. Stored as a `&'static` slice on [`HandlerDef`] so
/// the registry can return it without any allocation at call time.
///
/// The `param_type` field is drawn from a closed vocabulary (e.g. `"string"`,
/// `"uuid"`, `"boolean"`, `"integer"`), asserted as an exact set by a
/// registry-wide test. It does not validate the argument, but it is not
/// documentation-only either: the runtime derives each verb's published JSON
/// Schema from it, so an unmapped spelling withholds that verb's schema.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct ParamDef {
    /// Parameter name as used in the DSL (e.g. `"id"`, `"kind"`, `"query"`).
    pub name: &'static str,
    /// Type hint from the closed vocabulary (e.g. `"string"`, `"uuid"`, `"boolean"`).
    pub param_type: &'static str,
    /// Whether the caller must supply this parameter.
    pub required: bool,
    /// One-line human-readable description.
    pub description: &'static str,
    /// Identifier-resolution mode for `param_type` `"uuid"` or `"array of
    /// uuid"` parameters; [`IdResolutionMode::NotApplicable`] for every
    /// other parameter type.
    pub resolution_mode: IdResolutionMode,
}

/// Handler metadata for discovery and documentation.
///
/// Replaces the previous `VerbDef`. Every entry carries a `visibility` tag
/// so the registry can separate the MCP-exposed surface from internal handlers,
/// and a `category` that classifies the illocutionary force of the verb
/// per the speech-act taxonomy.
///
/// The `params` slice is used by `VerbRegistry::describe_verb` to build the
/// `help=true` schema envelope. Packs that predate this field leave it empty
/// (`&[]`) which is backward-compatible — callers receive a schema envelope
/// with zero params rather than an error.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct HandlerDef {
    pub name: &'static str,
    pub description: &'static str,
    pub visibility: Visibility,
    /// Illocutionary force classification. Use `Assertive` for `Subhandler`
    /// entries that have no external callers.
    pub category: VerbCategory,
    /// Parameter schema for `help=true` introspection.
    ///
    /// Empty (`&[]`) is the correct default for handlers that predate this
    /// field or have no fixed parameter schema (e.g. free-form query verbs).
    pub params: &'static [ParamDef],
}

/// Presentation override for a verb handler.
///
/// Most verbs use the default `Standard` policy which allows the caller's
/// requested `PresentationMode` to apply.  A small set declare `AlwaysVerbose`
/// because Agent-mode trimming (UUID shortening, empty-field dropping) would
/// corrupt their response for downstream chaining — e.g. `get` returns UUIDs
/// that callers pipe into `link`; shortening them here breaks the chain.
///
/// The policy is carried as a `const` in [`HandlerDef`] so the registry can
/// consult it before applying the presentation transform.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
pub enum VerbPresentationPolicy {
    /// Apply the caller's requested `PresentationMode` unchanged.
    #[default]
    Standard,
    /// Always use `Verbose` output regardless of the caller's mode.
    ///
    /// Declared verbs: `get`, `link`, `query`, `traverse`, `neighbors`,
    /// `brain.feedback`, `brain.auto_feedback`, `memory.feedback`,
    /// `comm.delivered`, `git.digest`, `git.ingest_cursor`.
    ///
    /// `link` is included because the returned edge ID is the only handle for
    /// follow-up `neighbors`/`traverse` calls; short-form IDs risk prefix
    /// collision at scale (~65K edges can share an 8-char prefix).
    ///
    /// `brain.feedback` is included because callers chain `target_id` from the
    /// response back into subsequent feedback or profile queries; an 8-char
    /// prefix is ambiguous and defeats the acknowledged-ID contract.
    /// `memory.feedback` has the same exact-target contract and rejects prefix
    /// resolution, so its acknowledged `target_id` must remain canonical.
    /// `brain.auto_feedback` acknowledges the same canonical `target_id` and
    /// feeds those strict paths, so it carries the same guarantee.
    /// `comm.delivered` is included because its `id` is an exact correlation
    /// key and the verb deliberately rejects prefix resolution (#1482).
    ///
    /// `git.digest` is included because its successful response is also the
    /// durable receipt payload. Presentation must not shorten `receipt_id` or
    /// otherwise make the returned result differ from the stored result.
    /// `git.ingest_cursor` preserves raw checkpoint strings, full project UUIDs,
    /// and stored microsecond timestamps for persisted-position inspection.
    AlwaysVerbose,
    /// Preserve only the root append receipt's `created_at` string in Agent mode.
    StreamAppendReceipt,
    /// Preserve `created_at` and `updated_at` strings on immediate `results`
    /// array members in Agent mode.
    StreamBatchReceipts,
}

impl HandlerDef {
    /// Resolve the presentation policy for this handler.
    ///
    /// Returns [`VerbPresentationPolicy::AlwaysVerbose`] for verbs whose
    /// semantics demand full output (full UUIDs, complete timestamps) regardless
    /// of the caller's requested presentation mode.
    ///
    /// Stream writers retain exact receipt timestamps while keeping other
    /// Agent transforms. Unlisted verbs use `Standard`.
    pub fn presentation_policy(&self) -> VerbPresentationPolicy {
        match self.name {
            "get"
            | "link"
            | "query"
            | "traverse"
            | "neighbors"
            | "brain.feedback"
            | "brain.auto_feedback"
            | "memory.feedback"
            | "comm.delivered"
            | "git.digest"
            | "git.ingest_cursor" => VerbPresentationPolicy::AlwaysVerbose,
            "stream.append" => VerbPresentationPolicy::StreamAppendReceipt,
            "stream.batch" => VerbPresentationPolicy::StreamBatchReceipts,
            _ => VerbPresentationPolicy::Standard,
        }
    }
}

/// Backward-compatible type alias.  Existing code that names `VerbDef` still
/// compiles; new code should use `HandlerDef` directly.
#[deprecated(since = "0.2.0", note = "Use HandlerDef instead")]
pub type VerbDef = HandlerDef;

/// Match spec for one end of an [`EdgeEndpointRule`].
///
/// Identifies a substrate + kind pair that the rule applies to. Note that
/// `kind` strings refer to the pack-declared note kinds / entity kinds — not
/// the closed [`EdgeRelation`] set, which is universal.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum EndpointKind {
    /// A note whose `kind` field equals the given string (e.g. `"task"`).
    NoteOfKind(&'static str),
    /// An entity whose `kind` field equals the given string (e.g. `"concept"`).
    EntityOfKind(&'static str),
    /// An entity whose base `kind` AND `entity_type` subtype both match the
    /// given strings (e.g. `kind: "concept", entity_type: "theorem"`). Both
    /// fields must match — enforcing the `(EntityKind, entity_type)` registry
    /// invariant required by ADR-001:102. Required for granular entity subtypes
    /// (formal-math theorem/definition, AMR gene/drug/pathogen): `EntityOfKind`
    /// only sees the base kind (`"concept"`), so an `EntityOfKind("theorem")`
    /// rule is silently inert. Additive — tightens nothing in the closed relation
    /// set.
    EntityOfType {
        /// Base entity kind that must match (e.g. `"concept"`).
        kind: &'static str,
        /// Canonical `entity_type` subtype that must match (e.g. `"theorem"`).
        entity_type: &'static str,
    },
}

/// A pack-declared endpoint rule for a specific edge relation.
///
/// Rules are **additive**: they extend the set of allowed
/// `(source, relation, target)` triples beyond the base contract.
/// Packs cannot tighten the base rules — only broaden them. The closed
/// [`EdgeRelation`] taxonomy itself is not extended; only the endpoint
/// contract per relation is.
///
/// Example — GTD pack allows `depends_on` between task notes:
///
/// ```ignore
/// EdgeEndpointRule {
///     relation: EdgeRelation::DependsOn,
///     source: EndpointKind::NoteOfKind("task"),
///     target: EndpointKind::NoteOfKind("task"),
/// }
/// ```
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct EdgeEndpointRule {
    pub relation: EdgeRelation,
    pub source: EndpointKind,
    pub target: EndpointKind,
}

/// Lifecycle specification for a note kind.
///
/// Declares which field holds the kind's domain state, the initial value,
/// terminal values, and allowed transitions.  The runtime uses this to
/// validate lifecycle operations at the verb boundary without hard-coding
/// kind-specific logic in the shared CRUD path.
///
/// Phase 1 (current): packs declare the spec; the runtime records it for
/// documentation and future enforcement.
/// Phase 2 (future): the runtime uses `field` to route lifecycle writes
/// to a first-class column rather than `properties`.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct NoteLifecycleSpec {
    /// The field name that holds the kind's lifecycle state.
    ///
    /// Use `"kind_status"` for pack-owned lifecycle fields to avoid the
    /// semantic collision with `Note.status` (NoteStatus).
    pub field: &'static str,
    /// The value assigned when a note of this kind is first created.
    pub initial: &'static str,
    /// Values from which no further transitions are possible.
    pub terminal: &'static [&'static str],
    /// Allowed `(from, to)` transitions. `"*"` as `from` matches any state.
    pub transitions: &'static [(&'static str, &'static str)],
}

/// Kind-level schema specification for a note kind.
///
/// Each pack-registered note kind may declare a `NoteKindSpec` to describe
/// its lifecycle semantics.  The runtime collects these at boot time via
/// [`Pack::NOTE_KIND_SPECS`] for documentation, introspection, and future
/// enforcement.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct NoteKindSpec {
    /// The note kind string this spec governs (e.g. `"task"`).
    pub kind: &'static str,
    /// Alternate names this kind accepts on the wire.
    pub aliases: &'static [&'static str],
    /// Lifecycle state machine for this kind.
    pub lifecycle: NoteLifecycleSpec,
}

/// SQLite storage type for a nullable pack-auxiliary column addition.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum PackColumnAffinity {
    /// A nullable `TEXT` column with no default or primary key.
    Text,
    /// A nullable `INTEGER` column with no default or primary key.
    Integer,
}

/// An idempotent nullable-column addition to a pack-owned auxiliary table.
///
/// Identifiers must use ASCII letters, digits, or underscores and cannot start
/// with a digit. Existing columns must match the declared type and have no
/// default, primary key, generated expression, or `NOT NULL` constraint. A
/// compatible partial upgrade completes without changing existing column values.
/// The pack's full create-table DDL must also include every declared column.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct PackColumnAddition {
    /// Pack-owned auxiliary table in the backend's main schema.
    pub table: &'static str,
    /// Column to add when absent from an existing table.
    pub column: &'static str,
    /// Exact declared SQLite type required for this column.
    pub affinity: PackColumnAffinity,
}

/// DDL statements the pack needs applied to the auxiliary schema.
///
/// Pack-auxiliary tables use idempotent `CREATE TABLE IF NOT EXISTS`; they are
/// not part of the core versioned migration chain.  The runtime applies these
/// statements once at pack registration time (or startup) against the active
/// storage backend.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct PackSchemaPlan {
    /// The pack this schema plan belongs to (used for error reporting).
    pub pack: &'static str,
    /// Idempotent SQL statements to apply.
    pub statements: &'static [&'static str],
}

/// A composable module that contributes vocabulary, verbs, and edge endpoint
/// rules to the khive runtime.
///
/// Packs declare what entity kinds, note kinds, and verbs they introduce, and
/// optionally extend the per-relation endpoint contract via [`EDGE_RULES`].
/// The runtime merges vocabularies from all loaded packs and rejects
/// unregistered kinds at the service boundary.
///
/// The closed [`EdgeRelation`] enum is not extensible — only its
/// per-relation endpoint contract is extensible by packs.
///
/// [`EDGE_RULES`]: Pack::EDGE_RULES
pub trait Pack {
    /// Short identifier for this pack (e.g. "kg", "tasks").
    const NAME: &'static str;

    /// Note kinds this pack contributes to the runtime vocabulary.
    const NOTE_KINDS: &'static [&'static str];

    /// Entity kinds this pack contributes to the runtime vocabulary.
    const ENTITY_KINDS: &'static [&'static str];

    /// Brain profile consumer kinds this pack requests.
    ///
    /// A pack that resolves a brain profile for a consumer (for example,
    /// `"recall"`) declares that wire-level kind here. The runtime composes
    /// declarations from all loaded packs so `brain.bind` can reject bindings
    /// that no registered consumer will ever request. Multiple packs may
    /// declare the same consumer kind; composition deduplicates them.
    ///
    /// The `"*"` binding wildcard is registry-owned and must not be declared
    /// by a pack.
    const BRAIN_CONSUMER_KINDS: &'static [&'static str] = &[];

    /// Handlers this pack registers.
    ///
    /// The runtime routes verb calls to the pack that declares them.
    /// Only entries with `visibility: Visibility::Verb` are surfaced on the
    /// MCP wire; `Visibility::Subhandler` entries are internal.
    const HANDLERS: &'static [HandlerDef];

    /// Additional edge endpoint rules this pack contributes.
    ///
    /// Defaults to empty — packs that introduce no new endpoint pairs (or
    /// only rely on the base endpoint contract) can ignore this.
    const EDGE_RULES: &'static [EdgeEndpointRule] = &[];

    /// Entity-type subtypes this pack contributes to the `(EntityKind,
    /// entity_type)` registry (the `entity_type` axis is distinct from and
    /// finer-grained than the closed [`EntityKind`](crate::entity::EntityKind)
    /// taxonomy — see `khive-types::entity_type::EntityTypeRegistry`).
    ///
    /// Defaults to empty, mirroring [`EDGE_RULES`]'s additive contract:
    /// packs that introduce no new subtypes can ignore this. Entries here
    /// are composed with `EntityTypeRegistry::builtin()` at runtime boot
    /// (`VerbRegistry::all_entity_types`); packs must declare only new
    /// `(kind, type_name)` pairs — they may not tighten or shadow a builtin
    /// or another pack's declared subtype.
    ///
    /// [`EDGE_RULES`]: Pack::EDGE_RULES
    const ENTITY_TYPES: &'static [EntityTypeDef] = &[];

    /// Other pack names whose vocabulary this pack references.
    ///
    /// The runtime checks that every name in `REQUIRES` appears in the
    /// loaded pack set before any pack is registered. Defaults to empty
    /// so existing packs compile without changes.
    const REQUIRES: &'static [&'static str] = &[];

    /// Lifecycle and schema specs for note kinds this pack owns.
    ///
    /// Packs that introduce note kinds with explicit lifecycle semantics
    /// (e.g. GTD's `task` kind) declare the spec here.  The runtime collects
    /// these at boot time for introspection and future enforcement.  Defaults
    /// to empty so existing packs compile without changes.
    const NOTE_KIND_SPECS: &'static [NoteKindSpec] = &[];

    /// Pack-auxiliary schema plan.
    ///
    /// Packs that need their own auxiliary tables (e.g. GTD's
    /// `gtd_lifecycle_audit`) declare idempotent DDL statements here.
    /// The runtime applies them once at registration time.  Defaults to
    /// `None` so packs with no auxiliary schema cost nothing.
    const SCHEMA_PLAN: Option<PackSchemaPlan> = None;

    /// Nullable-column upgrades for this pack's auxiliary tables.
    ///
    /// The backend validates and adds missing columns on existing tables before
    /// applying [`Self::SCHEMA_PLAN`], then validates the final schema. The
    /// entire plan is transactional. Absent tables are created only by the
    /// pack's full DDL, so unloaded packs do not acquire auxiliary tables.
    const SCHEMA_COLUMN_ADDITIONS: &'static [PackColumnAddition] = &[];

    /// Validation rule IDs contributed by this pack.
    ///
    /// Rule IDs are namespaced by pack name: `<pack-name>/<rule-id>`.
    /// The runtime merges rule IDs from all packs; the actual rule
    /// implementations live in `khive-runtime::validation::ValidationRule`
    /// (not in `khive-types`, which stays `no_std`). This const serves as
    /// the declarative catalog of rule identifiers so the validation
    /// infrastructure can enumerate what rules a pack claims without
    /// loading the runtime.
    ///
    /// Defaults to empty — packs with no domain-specific validation rules
    /// can leave this unset.
    const VALIDATION_RULES: &'static [&'static str] = &[];
}

/// ADR-099 D3 — the v1 atomic-admissible verb set for `--atomic` bulk apply.
///
/// This is an EXPLICIT per-verb allowlist, never derived from [`VerbCategory`]
/// or any other classification ("never a pack-level category", ADR-099 D3).
/// Every verb here has a prepare/apply seam whose in-transaction phase reduces
/// to synchronous DML — the atomic-unit suspend-free invariant
/// (`SqlAccess::atomic_unit` in `khive-storage`). Extending this list is a
/// design decision (ADR-099 amendment), not a code-review-only change; the
/// `atomic_admissible_list_matches_adr` test below pins this exact set so an
/// edit here forces the editor to touch that test and its ADR citation.
pub const ATOMIC_ADMISSIBLE_VERBS: &[&str] = &[
    "update",
    "delete",
    "link",
    "merge",
    "gtd.transition",
    "gtd.complete",
    "propose",
    "review",
    "withdraw",
];

/// Verbs rejected under `--atomic` because their write still computes an
/// embedding synchronously and no prepare/apply seam hoists that embedding
/// out of the transaction yet (ADR-099 D3, "v1 rejected — embedding-bearing").
const ATOMIC_EMBEDDING_BEARING_VERBS: &[&str] = &[
    "create",
    "memory.remember",
    "gtd.assign",
    "comm.send",
    "comm.reply",
    "comm.ingest",
];

/// Verbs on [`ATOMIC_ADMISSIBLE_VERBS`] (ADR-099 D3 conceptually admissible)
/// that have no *full-parity* prepare/apply seam yet, so they are rejected up
/// front (checked BEFORE the general admissible-list check) rather than
/// admitted with a silent gap. See
/// crates/khive-types/docs/api/pack.md#adr-099-d3-atomic-admissibility-rejection-classes
/// for why each verb is deferred and the ADR-099 B3 ordering rationale.
pub const ATOMIC_KNOWN_UNIMPLEMENTED_VERBS: &[&str] = &["propose", "review", "withdraw", "merge"];

/// Read verbs rejected under `--atomic` — they produce no write plan to apply
/// (ADR-099 D3, "v1 rejected — reads").
const ATOMIC_READ_VERBS: &[&str] = &[
    "search",
    "recall",
    "query",
    "traverse",
    "list",
    "get",
    "neighbors",
    "context",
    "stats",
    "verbs",
];

/// Conservative default maximum op count for one `--atomic` unit (ADR-099
/// migration step 7 / B3). Override per invocation with
/// `kkernel exec --atomic --atomic-max-ops N`. See
/// crates/khive-types/docs/api/pack.md#atomic_max_ops_default--2000--rationale
/// for why 2000 specifically was chosen and when to revisit it.
pub const ATOMIC_MAX_OPS_DEFAULT: usize = 2000;

/// Why a verb was rejected from an `--atomic` op list (ADR-099 D3, migration
/// step 2). Distinguishes the two named rejection classes from a generic
/// "not yet admitted" fallback so callers can produce an actionable message.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum AtomicRejectionReason {
    /// The verb still computes an embedding synchronously in its write path.
    EmbeddingBearing,
    /// The verb is a read — it has no write plan to apply.
    Read,
    /// Neither on the v1 admissible list nor a known rejected category (e.g.
    /// a verb added after this list was written). Rejected by default —
    /// admissibility is opt-in, never inferred.
    Unlisted,
    /// On [`ATOMIC_ADMISSIBLE_VERBS`] per ADR-099 D3 (conceptually admissible,
    /// intended to gain a seam) but has no prepare/apply implementation in
    /// this slice yet ([`ATOMIC_KNOWN_UNIMPLEMENTED_VERBS`]). Rejected at the
    /// same pre-runtime static-guard stage as every other rejection reason —
    /// never silently no-opped, never deferred until after a runtime/write
    /// attempt.
    KnownUnimplemented,
}

/// Static admissibility classification for `verb_name` under ADR-099
/// `--atomic` bulk apply.
///
/// Returns `None` when the verb is admissible; `Some(reason)` names why it is
/// rejected. Default-deny: a verb name absent from every list here is
/// [`AtomicRejectionReason::Unlisted`], never silently admitted.
///
/// `ATOMIC_KNOWN_UNIMPLEMENTED_VERBS` is checked BEFORE the general
/// admissible-list membership check (ADR-099 B3): those
/// verbs are members of `ATOMIC_ADMISSIBLE_VERBS`, so checking membership
/// first would admit them (`None`) and defer their rejection to prepare time,
/// after a runtime has already been constructed.
pub fn atomic_admissibility(verb_name: &str) -> Option<AtomicRejectionReason> {
    if ATOMIC_KNOWN_UNIMPLEMENTED_VERBS.contains(&verb_name) {
        return Some(AtomicRejectionReason::KnownUnimplemented);
    }
    if ATOMIC_ADMISSIBLE_VERBS.contains(&verb_name) {
        return None;
    }
    if ATOMIC_EMBEDDING_BEARING_VERBS.contains(&verb_name) {
        return Some(AtomicRejectionReason::EmbeddingBearing);
    }
    if ATOMIC_READ_VERBS.contains(&verb_name) {
        return Some(AtomicRejectionReason::Read);
    }
    Some(AtomicRejectionReason::Unlisted)
}

#[cfg(test)]
mod tests {
    use super::*;

    struct TestPack;

    impl Pack for TestPack {
        const NAME: &'static str = "test";
        const NOTE_KINDS: &'static [&'static str] = &["memo"];
        const ENTITY_KINDS: &'static [&'static str] = &["widget"];
        const HANDLERS: &'static [HandlerDef] = &[HandlerDef {
            name: "do_thing",
            description: "does a thing",
            visibility: Visibility::Verb,
            category: VerbCategory::Commissive,
            params: &[],
        }];
    }

    #[test]
    fn pack_trait_compiles() {
        assert_eq!(TestPack::NAME, "test");
        assert_eq!(TestPack::NOTE_KINDS, &["memo"]);
        assert_eq!(TestPack::ENTITY_KINDS, &["widget"]);
        assert_eq!(TestPack::HANDLERS.len(), 1);
        assert_eq!(TestPack::HANDLERS[0].name, "do_thing");
        assert_eq!(TestPack::HANDLERS[0].visibility, Visibility::Verb);
        assert_eq!(TestPack::HANDLERS[0].category, VerbCategory::Commissive);
    }

    #[test]
    fn verb_category_variants_exist() {
        // Just ensuring the enum variants are accessible — no runtime assertion
        // needed beyond confirming they exist at compile time.
        let _ = VerbCategory::Assertive;
        let _ = VerbCategory::Directive;
        let _ = VerbCategory::Commissive;
        let _ = VerbCategory::Declaration;
    }

    #[test]
    fn pack_validation_rules_default_empty() {
        assert!(TestPack::VALIDATION_RULES.is_empty());
    }

    #[test]
    fn pack_entity_types_default_empty() {
        assert!(TestPack::ENTITY_TYPES.is_empty());
    }

    // `link` must be AlwaysVerbose so edge IDs are not shortened.
    #[test]
    fn link_handler_is_always_verbose() {
        let link_def = HandlerDef {
            name: "link",
            description: "Create a typed directed edge",
            visibility: Visibility::Verb,
            category: VerbCategory::Commissive,
            params: &[],
        };
        assert_eq!(
            link_def.presentation_policy(),
            VerbPresentationPolicy::AlwaysVerbose,
            "link must be AlwaysVerbose"
        );
    }

    // AlwaysVerbose set regression: protect every identifier-bearing contract.
    #[test]
    fn always_verbose_set_contains_expected_verbs() {
        let always_verbose = [
            "get",
            "link",
            "query",
            "traverse",
            "neighbors",
            "brain.feedback",
            "brain.auto_feedback",
            "memory.feedback",
            "comm.delivered",
            "git.digest",
            "git.ingest_cursor",
        ];
        for name in always_verbose {
            let h = HandlerDef {
                name,
                description: "",
                visibility: Visibility::Verb,
                category: VerbCategory::Assertive,
                params: &[],
            };
            assert_eq!(
                h.presentation_policy(),
                VerbPresentationPolicy::AlwaysVerbose,
                "{name:?} must be AlwaysVerbose"
            );
        }
    }

    #[test]
    fn stream_receipt_policies_are_closed_to_the_registered_writers() {
        for (name, policy) in [
            ("stream.append", VerbPresentationPolicy::StreamAppendReceipt),
            ("stream.batch", VerbPresentationPolicy::StreamBatchReceipts),
            ("stream.read", VerbPresentationPolicy::Standard),
            ("stream.batch.other", VerbPresentationPolicy::Standard),
            ("list", VerbPresentationPolicy::Standard),
        ] {
            let handler = HandlerDef {
                name,
                description: "",
                visibility: Visibility::Verb,
                category: VerbCategory::Commissive,
                params: &[],
            };
            assert_eq!(handler.presentation_policy(), policy, "{name}");
        }
    }

    // Standard policy for all other verbs.
    #[test]
    fn non_verbose_verbs_are_standard_policy() {
        let standard = [
            "create", "list", "update", "delete", "search", "recall", "remember",
        ];
        for name in standard {
            let h = HandlerDef {
                name,
                description: "",
                visibility: Visibility::Verb,
                category: VerbCategory::Commissive,
                params: &[],
            };
            assert_eq!(
                h.presentation_policy(),
                VerbPresentationPolicy::Standard,
                "{name:?} must be Standard (not AlwaysVerbose)"
            );
        }
    }

    // ── ADR-099 D3 atomic admissibility ────────────────────────────────────

    // Drift-pin: a hardcoded copy of the ADR-099 D3 v1 admissible list. If
    // someone edits `ATOMIC_ADMISSIBLE_VERBS`, this test fails until they also
    // update this literal — forcing a look at ADR-099 D3 ("Decision: admit
    // only verbs that expose a prepare/apply seam...") before the set changes.
    #[test]
    fn atomic_admissible_list_matches_adr099_d3() {
        let adr_099_d3_v1_admissible_set: &[&str] = &[
            "update",
            "delete",
            "link",
            "merge",
            "gtd.transition",
            "gtd.complete",
            "propose",
            "review",
            "withdraw",
        ];
        assert_eq!(
            ATOMIC_ADMISSIBLE_VERBS, adr_099_d3_v1_admissible_set,
            "ATOMIC_ADMISSIBLE_VERBS drifted from ADR-099 D3's explicit v1 list"
        );
    }

    #[test]
    fn atomic_admissible_verbs_are_admitted() {
        for verb in ATOMIC_ADMISSIBLE_VERBS {
            // Governance verbs are on ATOMIC_ADMISSIBLE_VERBS per ADR-099 D3
            // (conceptually admissible) but are checked separately below:
            // they are rejected at this same static layer for a distinct
            // reason (KnownUnimplemented), not admitted (None).
            if ATOMIC_KNOWN_UNIMPLEMENTED_VERBS.contains(verb) {
                continue;
            }
            assert_eq!(
                atomic_admissibility(verb),
                None,
                "{verb:?} is on the v1 admissible list and must be admitted"
            );
        }
    }

    #[test]
    fn atomic_known_unimplemented_verbs_rejected_before_runtime() {
        // ADR-099 B3: propose/review/withdraw
        // remain on ATOMIC_ADMISSIBLE_VERBS (ADR-099 D3 intends them to gain a
        // seam) but must be rejected at this SAME static pre-runtime guard —
        // not admitted here and only failed later inside
        // `atomic_prepare::prepare_op` after a runtime was already built.
        for verb in ATOMIC_KNOWN_UNIMPLEMENTED_VERBS {
            assert!(
                ATOMIC_ADMISSIBLE_VERBS.contains(verb),
                "{verb:?} must remain on ATOMIC_ADMISSIBLE_VERBS per ADR-099 D3"
            );
            assert_eq!(
                atomic_admissibility(verb),
                Some(AtomicRejectionReason::KnownUnimplemented),
                "{verb:?} must be rejected as known-unimplemented, not admitted"
            );
        }
    }

    #[test]
    fn atomic_embedding_bearing_verbs_rejected_named() {
        for verb in [
            "create",
            "memory.remember",
            "gtd.assign",
            "comm.send",
            "comm.reply",
        ] {
            assert_eq!(
                atomic_admissibility(verb),
                Some(AtomicRejectionReason::EmbeddingBearing),
                "{verb:?} must be rejected as embedding-bearing (ADR-099 acceptance criteria)"
            );
        }
    }

    #[test]
    fn atomic_read_verbs_rejected() {
        for verb in [
            "search",
            "recall",
            "query",
            "traverse",
            "list",
            "get",
            "neighbors",
            "context",
        ] {
            assert_eq!(
                atomic_admissibility(verb),
                Some(AtomicRejectionReason::Read),
                "{verb:?} must be rejected as a read verb"
            );
        }
    }

    #[test]
    fn atomic_unknown_verb_defaults_to_unlisted_rejection() {
        assert_eq!(
            atomic_admissibility("some_future_verb_nobody_classified_yet"),
            Some(AtomicRejectionReason::Unlisted),
            "an unrecognized verb must default-deny, never silently admit"
        );
    }
}