// types.el — Shared type definitions for the Neuron intelligence layer.
//
// This file is the single source of truth for all domain types. Every
// subsystem imports from here. Types mirror the Rust domain types in
// neuron-domain/src/types.rs but are expressed in el so the
// runtime can reason over them as first-class graph entities.
//
// WHY el types instead of just Rust structs?
// The engram runtime needs to know the shape of each entity so it can
// build the spreading-activation index. Types declared here become graph
// schema — not just data holders.

// ── Core identifiers ──────────────────────────────────────────────────────────

// Uuid and String are primitive types provided by the engram runtime.
// We alias them here for readability in field annotations.

// ── Importance tier ───────────────────────────────────────────────────────────

// Importance drives how long a memory survives before the graph compacts it
// and how aggressively it participates in semantic activation.
enum Importance {
    Low,
    Normal,
    High,
    Critical,
}

// ── Knowledge tier ────────────────────────────────────────────────────────────

// Tiers encode epistemological confidence. Never skip tiers:
// note → lesson (proven ≥2 times) → canonical (stable, referenced widely).
enum KnowledgeTier {
    Note,
    Lesson,
    Canonical,
}

// ── Backlog types ─────────────────────────────────────────────────────────────

enum ItemType {
    Feature,
    Bug,
    Task,
    Chore,
}

// Priority P0 = ship-blocker, P3 = nice-to-have someday.
enum Priority {
    P0,
    P1,
    P2,
    P3,
}

// Status machine: draft → ready → in_progress → done | blocked | cancelled
enum BacklogStatus {
    Draft,
    Ready,
    InProgress,
    Done,
    Blocked,
    Cancelled,
}

// ── Context status ────────────────────────────────────────────────────────────

enum ContextStatus {
    Active,
    Completed,
    Archived,
}

// ── Gap direction (ISE) ───────────────────────────────────────────────────────

// Tracks whether Neuron's reasoning moved toward expression or suppression
// relative to its pre-reasoning state. Used for introspection and calibration.
enum GapDirection {
    TowardExpression,
    TowardSuppression,
    Neutral,
}

// ── Error variants ────────────────────────────────────────────────────────────

enum NeuronError {
    NotFound(String),
    StorageError(String),
    InvalidInput(String),
    Unauthorized(String),
    ConflictError(String),
}

// ── Domain types ──────────────────────────────────────────────────────────────

// Memory — an atomic piece of observed knowledge.
// supersedes_id links to the memory this one replaces, enabling memory chains.
type Memory {
    id: String,
    content: String,
    tags: [String],
    importance: String,
    project: String,
    supersedes_id: String?,
    created_at: String,
    updated_at: String,
}

// Knowledge — stable reference material. Lives longer than memories.
// key is the path-style identifier: "architecture/vbd/fundamentals.md"
type Knowledge {
    id: String,
    key: String,
    title: String,
    content: String,
    category: String,
    tier: String,
    tags: [String],
    project: String,
    created_at: String,
}

// BacklogItem — a unit of tracked work.
// depends_on is a list of item IDs that must complete before this one starts.
type BacklogItem {
    id: String,
    title: String,
    description: String,
    item_type: String,
    priority: String,
    status: String,
    project: String,
    tags: [String],
    depends_on: [String],
    created_at: String,
    updated_at: String,
}

// ContextStep — one recorded step inside an ExecutionContext.
// file_refs and key_decisions are captured so future sessions can replay
// the reasoning without replaying the entire conversation.
type ContextStep {
    action: String,
    status: String,
    timestamp: String,
    file_refs: [String],
    key_decisions: [String],
    notes: String,
}

// Context — tracks a multi-step execution in progress.
// This is what begin_work() / progress_work() operate on.
type Context {
    id: String,
    process_name: String,
    description: String,
    objective: String,
    project: String,
    status: String,
    steps: [ContextStep],
    file_refs: [String],
    key_decisions: [String],
    lessons_learned: [String],
    created_at: String,
    updated_at: String,
}

// Artifact — a versioned deliverable: plan, spec, report, design doc.
// version increments on every revise_artifact() call.
type Artifact {
    id: String,
    title: String,
    content: String,
    artifact_type: String,
    status: String,
    project: String,
    version: Int,
    created_at: String,
    updated_at: String,
}

// InternalStateEvent — Neuron's introspective record.
// Captures the gap between pre-reasoning and post-reasoning responses
// so Neuron can audit its own calibration over time.
type InternalStateEvent {
    id: String,
    trigger: String,
    pre_reasoning: String,
    post_reasoning: String,
    compression_ratio: String,
    gap_direction: String,
    tags: [String],
    logged_at: String,
}

// ConfigEntry — a runtime configuration key/value pair.
// Config changes are sealed operations — they affect Neuron's behavior globally.
type ConfigEntry {
    key: String,
    value: String,
    updated_at: String,
}

// GraphNode — a node returned by graph inspection or traversal.
// edges is a list of "relation:target_id" strings for human readability.
type GraphNode {
    entity_type: String,
    entity_id: String,
    label: String,
    edges: [String],
}

// SearchResult — returned by semantic (activate) queries.
// score is a float in [0.0, 1.0] representing similarity to the query.
type SearchResult {
    id: String,
    content: String,
    score: String,
    node_type: String,
}

// AxonToolCall — an incoming tool invocation from the Axon protocol.
type AxonToolCall {
    id: String,
    tool_name: String,
    params: Map<String, String>,
}

// AxonToolResult — the response envelope for an Axon tool call.
type AxonToolResult {
    id: String,
    call_id: String,
    result: Map<String, String>,
    error: String?,
}

// ProcessStep — one step inside a named Process workflow.
type ProcessStep {
    name: String,
    instructions: String,
    tools: [String],
}

// Process — a named, reusable workflow pattern.
// Registering processes with define_process() makes institutional knowledge
// executable — not just documented.
type Process {
    id: String,
    name: String,
    description: String,
    steps: [ProcessStep],
    created_at: String,
    updated_at: String,
}