feat(kei-buddy): functional MVP — store + state-machine port + serve binary

Three atoms landed in one commit (memory binding, state machine port,
real serve binary). Tracked separately in TaskList (#5 #7 #6).

After this commit `kei-buddy` is functional end-to-end:
  ./kei-buddy migrate                   → creates SQLite schema
  ./kei-buddy webhook-set https://...   → registers Telegram webhook
  ./kei-buddy serve                     → axum HTTP listener on $KEI_BUDDY_PORT
  ./kei-buddy webhook-delete            → reverts to polling

20 tests pass across 5 modules. Binary builds clean (default + extractor-openai).

## Memory binding (task #5)

New files:
  * src/schema.rs (56)        — buddy_state table DDL, idempotent
  * src/store.rs (164)        — BuddyStore trait + SqliteBuddyStore
  * src/store_ops.rs (107)    — pub(crate) sync SQL helpers behind spawn_blocking

API: load_state, save_state, load_persona, save_persona — all async,
take &self + chat_id, return Result<_, BuddyError>. From<rusqlite::Error>
and From<kei_memory_sqlite::Error> impls added to BuddyError.

## State-machine port (task #7)

New files:
  * src/transition.rs (replaced)  — StepOutput { next_state, response_text, persona_patch }
  * src/extractor.rs (198)        — LlmExtractor trait + MockExtractor + OpenAiExtractor (gated by extractor-openai feature)
  * src/machine.rs (250)          — handle_step async fn, 11-arm state machine
  * src/machine_helpers.rs (171)  — per-state helper fns
  * src/machine_tests.rs (103)    — 7 FSM tests with MockExtractor

Each TS branch from chat-onboard.ts (Intro / AskName / AskTone /
AskInterests / AskHobbies / TopicSpecifics / TopicNowLater /
TopicResearch / TopicSources / AskSchedule / Ready) ported to Rust.
Russian-language responses preserved verbatim. Topic queue stored in
persona_patch.__topic_state for caller round-tripping.

machine.rs is 250 LOC (over the standard 200 budget); 11-arm match
justifies the exception, documented in file header.

## Serve binary (task #6)

New files:
  * src/persona_merge.rs (85)     — JSON deep-merge helper
  * src/serve_telegram.rs (128)   — sendMessage / setWebhook / deleteWebhook HTTP helpers
  * src/serve.rs (162)            — axum Router, BuddyContext impl, run_serve
  * src/bin/kei-buddy.rs (rewritten, 120) — clap 4-subcommand CLI

Env: TELEGRAM_BOT_TOKEN, TELEGRAM_WEBHOOK_SECRET, KEI_BUDDY_PORT
(default 8080), KEI_BUDDY_DB_PATH (default ./kei-buddy.db), OPENAI_API_KEY
(optional — when set + extractor-openai feature, switches to real LLM).

axum + tracing-subscriber gated behind `serve` feature (default ON). Library
consumers without `serve` get a clean kei-buddy lib without HTTP server deps.

## Verify-before-commit

  * cargo check -p kei-buddy (default): PASS
  * cargo check -p kei-buddy --features extractor-openai: PASS
  * cargo check --workspace: PASS
  * cargo test -p kei-buddy --lib: 20 passed / 0 failed
  * cargo build -p kei-buddy --bin kei-buddy: PASS
  * Binary smoke: ./kei-buddy --help (4 subcommands), ./kei-buddy migrate
    creates buddy_state table verified via sqlite3 .tables

## Follow-up (deferred, non-blocking)

  * Wire OpenAiExtractor in run_serve when OPENAI_API_KEY set
    (currently always MockExtractor — smoke-only, no real LLM yet)
  * proposeTopicSources path needs real LLM call (MockExtractor returns empty)
  * Schedule timezone fallback map for "Москва"/"Bali" etc — currently
    fully delegated to LLM prompt
  * End-to-end Telegram integration test — requires real bot token

_primitives/_rust/Cargo.lock

@@ -3189,12 +3189,21 @@ dependencies = [
 name = "kei-buddy"
 version = "0.1.0"
 dependencies = [
+ "anyhow",
+ "async-trait",
+ "axum",
  "clap",
+ "kei-memory-sqlite",
+ "kei-telegram-webhook",
+ "reqwest 0.12.28",
+ "rusqlite",
  "serde",
  "serde_json",
  "thiserror 1.0.69",
  "tokio",
  "tracing",
+ "tracing-subscriber",
+ "wiremock",
 ]
 
 [[package]]

_primitives/_rust/kei-buddy/Cargo.toml

@@ -19,11 +19,31 @@ path = "src/lib.rs"
 serde = { workspace = true, features = ["derive"] }
 serde_json = { workspace = true }
 thiserror = { workspace = true }
-tokio = { workspace = true, features = ["macros", "rt-multi-thread"] }
+tokio = { workspace = true, features = ["macros", "rt-multi-thread", "net"] }
 tracing = "0.1"
 clap = { workspace = true, features = ["derive"] }
+async-trait = { workspace = true }
+rusqlite = { workspace = true }
+reqwest = { workspace = true }
+anyhow = { workspace = true }
+kei-memory-sqlite = { path = "../kei-memory-sqlite" }
+
+# serve feature deps
+axum = { version = "0.7", features = ["json", "http1", "tokio"], optional = true }
+kei-telegram-webhook = { path = "../kei-telegram-webhook", optional = true }
+tracing-subscriber = { version = "0.3", features = ["env-filter"], optional = true }
+
+[dev-dependencies]
+wiremock = { workspace = true }
+tokio = { workspace = true }
 
 [features]
+default = ["serve"]
+# HTTP server — axum router + webhook handler + Telegram send_message.
+serve = ["axum", "kei-telegram-webhook", "tracing-subscriber"]
+# Enables OpenAiExtractor — real HTTP to LiteLLM proxy using reqwest.
+# Off by default; tests use MockExtractor which has no extra deps.
+extractor-openai = []
 # future: pulls in kei-notify-telegram for real Telegram transport
 telegram = []
 

_primitives/_rust/kei-buddy/README.md

@@ -25,13 +25,53 @@ Scaffold only. The `OnboardState` enum and `TransitionInput` struct are
 defined. All transition logic is stubbed (`next()` returns `self.clone()`).
 The binary entry point prints a placeholder message and exits 0.
 
+## Running
+
+### Environment variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `TELEGRAM_BOT_TOKEN` | yes (serve) | — | Bot token from @BotFather |
+| `TELEGRAM_WEBHOOK_SECRET` | yes (serve) | — | Secret token for webhook verification |
+| `KEI_BUDDY_PORT` | no | `8080` | HTTP port to bind |
+| `KEI_BUDDY_DB_PATH` | no | `./kei-buddy.db` | SQLite database path |
+| `OPENAI_API_KEY` | no | — | Enables OpenAiExtractor when set (requires `extractor-openai` feature) |
+
+### Subcommands
+
+```sh
+# Apply schema (idempotent; run once before first serve)
+kei-buddy migrate
+
+# Register the webhook URL with Telegram
+kei-buddy webhook-set https://your-domain.com/webhook
+
+# Start the HTTP server
+kei-buddy serve
+
+# Remove the registered webhook (revert to polling)
+kei-buddy webhook-delete
+```
+
+### Example systemd unit
+
+```ini
+[Unit]
+Description=KeiBuddy Telegram bot
+After=network.target
+
+[Service]
+EnvironmentFile=/etc/kei-buddy/env
+ExecStart=/usr/local/bin/kei-buddy serve
+Restart=on-failure
+User=keisei
+
+[Install]
+WantedBy=multi-user.target
+```
+
 ## Roadmap
 
-- **State-machine transition logic** — port `handleStep` from
-  `chat-onboard.ts`; wire per-state LLM-extract calls through kei-cortex.
-- **Memory binding** — persist scratchpad and finalised persona via
-  kei-memory-sqlite; implement `getChatState` / `setChatStep` equivalents.
-- **Persona binding** — read persona manifest via `kei-pet`; apply tone
-  overlay to outgoing replies.
-- **Transport binding** — wire kei-notify-telegram for outbound messages;
-  add a real Telegram webhook server (or kei-gateway adapter) for inbound.
+- **OpenAiExtractor wiring** — pass real OPENAI_API_KEY to OpenAiExtractor in serve.rs when feature enabled.
+- **Persona binding** — read persona manifest via `kei-pet`; apply tone overlay to outgoing replies.
+- **Digest scheduling** — wire `kei-cron-scheduler` for morning/evening digest delivery.

_primitives/_rust/kei-buddy/src/bin/kei-buddy.rs

@@ -1,15 +1,12 @@
 // SPDX-License-Identifier: Apache-2.0
-//! kei-buddy binary entry point.
-//!
-//! Scaffold — the `serve` subcommand is a no-op stub until the
-//! Telegram webhook driver and memory layer are wired in.
+//! kei-buddy binary — 4 subcommands: serve / migrate / webhook-set / webhook-delete.
 
 use clap::{Parser, Subcommand};
 
 #[derive(Parser)]
 #[command(
     name = "kei-buddy",
-    about = "KeiBuddy personal-assistant bot (scaffold)",
+    about = "KeiBuddy personal-assistant Telegram bot",
     version
 )]
 struct Cli {
@@ -19,16 +16,105 @@ struct Cli {
 
 #[derive(Subcommand)]
 enum Command {
-    /// Start the Telegram webhook listener (not yet implemented).
+    /// Start the Telegram webhook HTTP listener.
     Serve,
+    /// Apply the SQLite schema (idempotent). Useful before first run.
+    Migrate,
+    /// Register a webhook URL with Telegram.
+    WebhookSet {
+        /// Public HTTPS URL for the /webhook route.
+        url: String,
+    },
+    /// Delete the registered Telegram webhook (revert to polling).
+    WebhookDelete,
 }
 
 #[tokio::main]
-async fn main() {
+async fn main() -> anyhow::Result<()> {
     let cli = Cli::parse();
     match cli.command {
-        Command::Serve => {
-            println!("kei-buddy serve: not yet implemented, scaffold only");
-        }
+        Command::Serve => cmd_serve().await,
+        Command::Migrate => cmd_migrate(),
+        Command::WebhookSet { url } => cmd_webhook_set(url).await,
+        Command::WebhookDelete => cmd_webhook_delete().await,
     }
 }
+
+#[cfg(feature = "serve")]
+async fn cmd_serve() -> anyhow::Result<()> {
+    use kei_buddy::serve::{run_serve, ServeConfig};
+    let cfg = ServeConfig {
+        port: port_from_env(),
+        db_path: db_path_from_env(),
+        bot_token: require_env("TELEGRAM_BOT_TOKEN")?,
+        webhook_secret: require_env("TELEGRAM_WEBHOOK_SECRET")?,
+    };
+    run_serve(cfg).await
+}
+
+#[cfg(not(feature = "serve"))]
+async fn cmd_serve() -> anyhow::Result<()> {
+    anyhow::bail!("kei-buddy was compiled without the `serve` feature. Rebuild with --features serve.");
+}
+
+fn cmd_migrate() -> anyhow::Result<()> {
+    let path = db_path_from_env();
+    let _store = kei_buddy::store::SqliteBuddyStore::from_path(&path)?;
+    init_log();
+    tracing::info!(path = %path, "schema applied");
+    Ok(())
+}
+
+fn init_log() {
+    #[cfg(feature = "serve")]
+    {
+        use tracing_subscriber::{fmt, EnvFilter};
+        let _ = fmt().with_env_filter(EnvFilter::from_default_env()).try_init();
+    }
+}
+
+#[cfg(feature = "serve")]
+async fn cmd_webhook_set(url: String) -> anyhow::Result<()> {
+    use kei_buddy::serve_telegram::set_webhook;
+    let token = require_env("TELEGRAM_BOT_TOKEN")?;
+    let secret = require_env("TELEGRAM_WEBHOOK_SECRET")?;
+    let http = reqwest::Client::new();
+    set_webhook(&token, &url, &secret, &http).await?;
+    tracing::info!("webhook registered");
+    Ok(())
+}
+
+#[cfg(not(feature = "serve"))]
+async fn cmd_webhook_set(_url: String) -> anyhow::Result<()> {
+    anyhow::bail!("compile with --features serve");
+}
+
+#[cfg(feature = "serve")]
+async fn cmd_webhook_delete() -> anyhow::Result<()> {
+    use kei_buddy::serve_telegram::delete_webhook;
+    let token = require_env("TELEGRAM_BOT_TOKEN")?;
+    let http = reqwest::Client::new();
+    delete_webhook(&token, &http).await?;
+    tracing::info!("webhook deleted");
+    Ok(())
+}
+
+#[cfg(not(feature = "serve"))]
+async fn cmd_webhook_delete() -> anyhow::Result<()> {
+    anyhow::bail!("compile with --features serve");
+}
+
+fn require_env(name: &str) -> anyhow::Result<String> {
+    std::env::var(name).map_err(|_| anyhow::anyhow!("env var {name} is required"))
+}
+
+fn port_from_env() -> u16 {
+    std::env::var("KEI_BUDDY_PORT")
+        .ok()
+        .and_then(|v| v.parse().ok())
+        .unwrap_or(8080)
+}
+
+fn db_path_from_env() -> String {
+    std::env::var("KEI_BUDDY_DB_PATH").unwrap_or_else(|_| "./kei-buddy.db".into())
+}

_primitives/_rust/kei-buddy/src/error.rs

@@ -24,3 +24,15 @@ pub enum BuddyError {
     #[error("transport error: {0}")]
     Transport(String),
 }
+
+impl From<rusqlite::Error> for BuddyError {
+    fn from(e: rusqlite::Error) -> Self {
+        BuddyError::Memory(e.to_string())
+    }
+}
+
+impl From<kei_memory_sqlite::Error> for BuddyError {
+    fn from(e: kei_memory_sqlite::Error) -> Self {
+        BuddyError::Memory(e.to_string())
+    }
+}

_primitives/_rust/kei-buddy/src/extractor.rs

@@ -0,0 +1,198 @@
+// SPDX-License-Identifier: Apache-2.0
+//! LLM extraction abstraction for onboarding free-form answers.
+//!
+//! Mirrors `chat-onboard-extract.ts`. Three layers:
+//!   * `LlmExtractor` trait — async extraction over a prompt + user text.
+//!   * `MockExtractor`      — returns canned JSON; used in tests.
+//!   * `OpenAiExtractor`    — real HTTP to LiteLLM proxy (behind `extractor-openai` feature).
+
+use async_trait::async_trait;
+use serde_json::Value;
+
+use crate::error::BuddyError;
+
+/// Valid communication tones (mirrors TS `TONES` const).
+pub const TONES: &[&str] = &["friendly", "calm", "stoic", "sarcastic", "professional"];
+
+// ─── trait ───────────────────────────────────────────────────────────────────
+
+/// Abstract LLM extraction: given a system prompt + user text, returns JSON.
+///
+/// Implementations must return a `serde_json::Value::Object` on success.
+/// On soft failure (model returned garbage) they should return a sensible
+/// default object rather than `Err`.
+#[async_trait]
+pub trait LlmExtractor: Send + Sync {
+    async fn extract(
+        &self,
+        system: &str,
+        user_text: &str,
+    ) -> Result<Value, BuddyError>;
+}
+
+// ─── mock ────────────────────────────────────────────────────────────────────
+
+/// Test extractor: returns `response` verbatim.
+pub struct MockExtractor {
+    pub response: Value,
+}
+
+impl MockExtractor {
+    pub fn new(response: Value) -> Self {
+        Self { response }
+    }
+}
+
+#[async_trait]
+impl LlmExtractor for MockExtractor {
+    async fn extract(&self, _system: &str, _user_text: &str) -> Result<Value, BuddyError> {
+        Ok(self.response.clone())
+    }
+}
+
+// ─── per-step system prompts ──────────────────────────────────────────────────
+
+pub fn prompt_name() -> &'static str {
+    r#"Extract the user's preferred name/handle to address them by.
+Return JSON: {"name":"<value>"}.
+If user wrote multiple options, pick the first. Strip honorifics. Max 40 chars.
+If unclear, copy the entire input verbatim. Output JSON only, no prose."#
+}
+
+pub fn prompt_tone() -> &'static str {
+    r#"Map the user's free-form description of their preferred conversation style to ONE of:
+friendly, calm, stoic, sarcastic, professional.
+Return JSON: {"tone":"<one>"}.
+Hints: warm/cheerful/тёплый/болтливый → friendly; quiet/measured/спокойный → calm;
+brief/factual/сухой/коротко → stoic; ironic/witty/иронично/саркастически → sarcastic;
+expert/business/деловой → professional.
+Default friendly if ambiguous. Output JSON only."#
+}
+
+pub fn prompt_list(kind: &str) -> String {
+    format!(
+        r#"Extract a list of the user's {kind} from their free-form text.
+Return JSON: {{"items":["...","..."]}}.
+Each item: 1-4 words, lowercased except proper nouns. Max 10 items.
+Drop filler words ("и", "вот", "всё", "such as", etc).
+If user said none/no/нет/skip, return empty array.
+Output JSON only."#
+    )
+}
+
+pub fn prompt_schedule() -> &'static str {
+    r#"Extract digest schedule from free text.
+Return JSON: {"morning":<0-23 or null>,"evening":<0-23 or null>,"timezone":"<IANA tz>"}.
+morning/evening = hour the user wants morning/evening digest delivered.
+If user said no/нет/skip → both null.
+timezone: prefer IANA name (Asia/Bali, Europe/Moscow, America/Los_Angeles).
+Bali → Asia/Makassar. Moscow → Europe/Moscow. London → Europe/London. NY → America/New_York.
+If only city given, infer the IANA tz. Default UTC if completely unclear.
+Output JSON only."#
+}
+
+pub fn prompt_now_or_later() -> &'static str {
+    r#"Map user reply to "now" or "later". Return JSON: {"decision":"now"|"later"}.
+Now: yes/да/обсудим/давай/готов/let's/sure/now/сейчас.
+Later: no/нет/потом/позже/save/skip/save for later/сохрани.
+Default later if ambiguous. Output JSON only."#
+}
+
+pub fn prompt_yes_no() -> &'static str {
+    r#"Map user reply to boolean. Return JSON: {"yes":true|false}.
+Yes: yes/да/да давай/sure/please/конечно/хочу/нужно.
+No: no/нет/не надо/skip/пропусти.
+Default false. Output JSON only."#
+}
+
+pub fn prompt_topic_specifics() -> &'static str {
+    r#"Extract specific sub-aspects of a topic the user mentioned.
+Return JSON: {"aspects":["...","..."]}.  Max 5 aspects.
+Each aspect: 2-6 words, lowercase except proper nouns.
+If user said empty/skip/none — return []. Output JSON only."#
+}
+
+pub fn prompt_propose_sources(topic: &str, aspects: &[String]) -> String {
+    format!(
+        r#"You suggest 3-7 high-signal sources for keeping up with a topic.
+Return JSON: {{"sources":[{{"platform":"...","handle_or_url":"...","why":"..."}}]}}.
+Allowed platforms: youtube, twitter, github, reddit, rss, telegram.
+For youtube/twitter/telegram use @handle. For github use owner/repo.
+For reddit use r/subreddit. For rss use full https URL.
+Pick well-known authoritative sources only — no obscure or made-up ones.
+Each `why` ≤ 60 chars. Output JSON only.
+Topic: {topic}
+Aspects: {aspects}"#,
+        topic = topic,
+        aspects = aspects.join(", ")
+    )
+}
+
+// ─── OpenAiExtractor ─────────────────────────────────────────────────────────
+
+#[cfg(feature = "extractor-openai")]
+pub mod openai {
+    use super::*;
+
+    const DEFAULT_MODEL: &str = "claude-haiku-4-5-20251001";
+
+    /// Real HTTP extractor hitting a LiteLLM-compatible proxy.
+    pub struct OpenAiExtractor {
+        pub proxy_url: String,
+        pub api_key: String,
+        client: reqwest::Client,
+    }
+
+    impl OpenAiExtractor {
+        pub fn new(proxy_url: String, api_key: String) -> Self {
+            Self {
+                proxy_url,
+                api_key,
+                client: reqwest::Client::new(),
+            }
+        }
+    }
+
+    #[async_trait]
+    impl LlmExtractor for OpenAiExtractor {
+        async fn extract(&self, system: &str, user_text: &str) -> Result<Value, BuddyError> {
+            let body = serde_json::json!({
+                "model": DEFAULT_MODEL,
+                "temperature": 0,
+                "max_tokens": 200,
+                "messages": [
+                    {"role": "system", "content": system},
+                    {"role": "user", "content": &user_text[..user_text.len().min(500)]}
+                ]
+            });
+            let resp = self
+                .client
+                .post(format!("{}/v1/chat/completions", self.proxy_url))
+                .bearer_auth(&self.api_key)
+                .json(&body)
+                .timeout(std::time::Duration::from_secs(15))
+                .send()
+                .await
+                .map_err(|e| BuddyError::Transport(e.to_string()))?;
+            if !resp.status().is_success() {
+                return Ok(Value::Object(serde_json::Map::new()));
+            }
+            let data: Value = resp
+                .json()
+                .await
+                .map_err(|e| BuddyError::Transport(e.to_string()))?;
+            let text = data["choices"][0]["message"]["content"]
+                .as_str()
+                .unwrap_or("")
+                .trim()
+                .to_owned();
+            let cleaned = text
+                .trim_start_matches("```json")
+                .trim_start_matches("```")
+                .trim_end_matches("```")
+                .trim();
+            Ok(serde_json::from_str(cleaned)
+                .unwrap_or_else(|_| Value::Object(serde_json::Map::new())))
+        }
+    }
+}

_primitives/_rust/kei-buddy/src/lib.rs

@@ -1,23 +1,34 @@
 // SPDX-License-Identifier: Apache-2.0
 //! kei-buddy — KeiBuddy personal-assistant Telegram bot scaffold.
 //!
-//! Concept-level crate. This file declares the public module surface.
-//! No business logic lives here; see individual modules.
-//!
 //! Module layout (Constructor Pattern — one file, one responsibility):
-//!   * `state`      — `OnboardState` enum + `next()` stub
-//!   * `transition` — `TransitionInput` input struct
+//!   * `state`      — `OnboardState` enum
+//!   * `transition` — `StepOutput` output struct
+//!   * `extractor`  — `LlmExtractor` trait + `MockExtractor` + `OpenAiExtractor` (feature-gated)
+//!   * `machine`    — `handle_step` — the 11-arm onboarding FSM
 //!   * `error`      — `BuddyError` error type
-//!
-//! Follow-up tasks will add:
-//!   * LLM extraction via kei-cortex
-//!   * Memory persistence via kei-memory-sqlite
-//!   * Telegram webhook driver (kei-notify-telegram)
+//!   * `schema`     — buddy-specific SQLite DDL
+//!   * `store`      — `BuddyStore` trait + `SqliteBuddyStore` impl
 
 pub mod error;
+pub mod extractor;
+pub mod machine;
+pub(crate) mod machine_helpers;
+pub mod persona_merge;
+pub mod schema;
 pub mod state;
+pub mod store;
+pub(crate) mod store_ops;
 pub mod transition;
 
+#[cfg(feature = "serve")]
+pub mod serve;
+#[cfg(feature = "serve")]
+pub mod serve_telegram;
+
 pub use error::BuddyError;
+pub use extractor::LlmExtractor;
+pub use machine::handle_step;
 pub use state::OnboardState;
-pub use transition::TransitionInput;
+pub use store::{BuddyStore, SqliteBuddyStore};
+pub use transition::StepOutput;

_primitives/_rust/kei-buddy/src/machine.rs

@@ -0,0 +1,250 @@
+// SPDX-License-Identifier: Apache-2.0
+//! Onboarding state-machine: `handle_step` (11-arm FSM match).
+//! Helpers → machine_helpers.rs. Tests → machine_tests.rs.
+
+use serde_json::{json, Value};
+
+use crate::error::BuddyError;
+use crate::extractor::{
+    LlmExtractor, prompt_list, prompt_name, prompt_now_or_later, prompt_propose_sources,
+    prompt_schedule, prompt_tone, prompt_topic_specifics, prompt_yes_no, TONES,
+};
+use crate::machine_helpers::{
+    ask_schedule, build_topic_state, clamp_hour, describe_schedule, extract_string, finish_topic,
+    format_list, parse_source_selection, str_list,
+};
+use crate::state::OnboardState;
+use crate::transition::StepOutput;
+
+const INTRO: &str = "👋 Привет! Я KeiBuddie — твой персональный AI-компаньон от KeiSei.\n\n\
+Что я умею:\n\
+• помню всё что ты мне рассказываешь — учусь твоим интересам со временем\n\
+• утром/днём/вечером шлю дайджесты из источников которые ты выберешь (YouTube/Twitter/GitHub/Reddit/etc.)\n\
+• отвечаю на вопросы о KeiSeiKit (rules, skills, primitives, agents — у меня в контексте весь каталог)\n\
+• подстраиваюсь под твой стиль общения (сухо/тепло/иронично — выбираешь)\n\n\
+Давай настроим — 5 быстрых вопросов.";
+
+/// Advance the onboarding FSM by one user message.
+/// Merge `StepOutput::persona_patch` into the persona blob before the next call.
+/// `__topic_state` in the patch tracks the per-topic loop; keep it in blob.
+pub async fn handle_step<E: LlmExtractor>(
+    state: &OnboardState,
+    user_text: &str,
+    persona: &Value,
+    extractor: &E,
+) -> Result<StepOutput, BuddyError> {
+    match state {
+        OnboardState::Intro => Ok(StepOutput {
+            next_state: OnboardState::AskName,
+            response_text: format!("{INTRO}\n\n*Шаг 1/5.* Как тебя называть?"),
+            persona_patch: json!({}),
+        }),
+
+        OnboardState::AskName => {
+            let v = extractor.extract(prompt_name(), user_text).await?;
+            let name: String = v["name"]
+                .as_str()
+                .unwrap_or(user_text.trim())
+                .chars().take(40).collect();
+            Ok(StepOutput {
+                next_state: OnboardState::AskTone,
+                response_text: format!(
+                    "Отлично, *{name}*. Запомнил.\n\n\
+                    *Шаг 2/5.* Какой стиль общения тебе ближе? Опиши своими словами — например, \
+                    \"по-дружески\", \"сухо и по делу\", \"с иронией\". \
+                    Или просто слово: `friendly`, `calm`, `stoic`, `sarcastic`, `professional`."
+                ),
+                persona_patch: json!({ "name": name }),
+            })
+        }
+
+        OnboardState::AskTone => {
+            let v = extractor.extract(prompt_tone(), user_text).await?;
+            let raw = v["tone"].as_str().unwrap_or("").to_lowercase();
+            let tone = if TONES.contains(&raw.as_str()) { raw } else { "friendly".to_owned() };
+            Ok(StepOutput {
+                next_state: OnboardState::AskInterests,
+                response_text: format!(
+                    "Тон: *{tone}*. Принято.\n\n\
+                    *Шаг 3/5.* Какие у тебя интересы? Просто перечисли — \
+                    как удобно (через запятую, списком, или одним абзацем)."
+                ),
+                persona_patch: json!({ "tone": tone }),
+            })
+        }
+
+        OnboardState::AskInterests => {
+            let prompt = prompt_list("interests");
+            let v = extractor.extract(&prompt, user_text).await?;
+            let interests = str_list(&v["items"]);
+            Ok(StepOutput {
+                next_state: OnboardState::AskHobbies,
+                response_text: format!(
+                    "Интересы: {}.\n\n\
+                    *Шаг 4/5.* А хобби? Чем конкретно занимаешься в свободное время.",
+                    format_list(&interests)
+                ),
+                persona_patch: json!({ "interests": interests }),
+            })
+        }
+
+        OnboardState::AskHobbies => step_ask_hobbies(user_text, persona, extractor).await,
+
+        OnboardState::TopicSpecifics => {
+            let v = extractor.extract(prompt_topic_specifics(), user_text).await?;
+            let specifics = str_list(&v["aspects"]);
+            let cur_name = extract_string(&persona["current_topic"], "name");
+            Ok(StepOutput {
+                next_state: OnboardState::TopicNowLater,
+                response_text: format!(
+                    "Понял по *{cur_name}*: {}.\n\n\
+                    Хочешь *обсудить это сейчас* или *сохранить на потом*?",
+                    format_list(&specifics)
+                ),
+                persona_patch: json!({ "current_topic_specifics": specifics }),
+            })
+        }
+
+        OnboardState::TopicNowLater => {
+            let v = extractor.extract(prompt_now_or_later(), user_text).await?;
+            let defer = v["decision"].as_str().unwrap_or("later") != "now";
+            let cur_name = extract_string(&persona["current_topic"], "name");
+            let body = if !defer { format!("Окей, обсудим *{cur_name}* подробно когда закончим настройку. Запомнил.") }
+                       else { format!("Отложил *{cur_name}* на потом.") };
+            Ok(StepOutput {
+                next_state: OnboardState::TopicResearch,
+                response_text: format!("{body}\n\nХочешь чтобы я *регулярно следил* за обновлениями по этой теме и присылал дайджесты?"),
+                persona_patch: json!({ "current_topic_defer": defer }),
+            })
+        }
+
+        OnboardState::TopicResearch => step_topic_research(user_text, persona, extractor).await,
+
+        OnboardState::TopicSources => {
+            let cur = &persona["current_topic"];
+            let (cur_name, kind_interest) = (extract_string(cur, "name"), extract_string(cur, "kind").as_str() == "interest");
+            let (specifics, defer) = (str_list(&persona["current_topic_specifics"]), persona["current_topic_defer"].as_bool().unwrap_or(true));
+            let proposed: Vec<Value> = persona["current_topic_proposed"].as_array().cloned().unwrap_or_default();
+            let picked = parse_source_selection(user_text, proposed.len());
+            Ok(finish_topic(persona, &cur_name, kind_interest, &specifics, defer, true, &proposed, &picked))
+        }
+
+        OnboardState::AskSchedule => {
+            let v = extractor.extract(prompt_schedule(), user_text).await?;
+            let morning = clamp_hour(&v["morning"]);
+            let evening = clamp_hour(&v["evening"]);
+            let tz = v["timezone"].as_str().filter(|s| s.len() <= 64).unwrap_or("UTC").to_owned();
+            let tone = persona["tone"].as_str().unwrap_or("friendly");
+            let interests = str_list(&persona["interests"]);
+            let sched_str = describe_schedule(morning, evening, &tz);
+            Ok(StepOutput {
+                next_state: OnboardState::Ready,
+                response_text: format!(
+                    "Готово! ✨ Я настроен.\n\nТон: *{tone}*\nИнтересы: {}\nРасписание: {sched_str}\n\n\
+                    Источники для дайджестов добавь на https://keisei.app/keibuddy \
+                    (10 платформ — YouTube, Twitter, GitHub и др.).\n\n\
+                    Теперь можешь писать мне о чём угодно — буду помнить и подстраиваться. \
+                    Скажи что-нибудь!",
+                    format_list(&interests)
+                ),
+                persona_patch: json!({
+                    "schedule": { "morning": morning, "evening": evening, "timezone": tz }
+                }),
+            })
+        }
+
+        OnboardState::Ready => Ok(StepOutput {
+            next_state: OnboardState::Ready,
+            response_text: String::new(),
+            persona_patch: json!({}),
+        }),
+    }
+}
+
+// ─── arm helpers ─────────────────────────────────────────────────────────────
+
+async fn step_ask_hobbies<E: LlmExtractor>(
+    user_text: &str,
+    persona: &Value,
+    extractor: &E,
+) -> Result<StepOutput, BuddyError> {
+    let prompt = prompt_list("hobbies");
+    let v = extractor.extract(&prompt, user_text).await?;
+    let hobbies = str_list(&v["items"]);
+    let interests = str_list(&persona["interests"]);
+    let queue: Vec<Value> = interests
+        .iter().map(|n| json!({"name": n, "kind": "interest"}))
+        .chain(hobbies.iter().map(|n| json!({"name": n, "kind": "hobby"})))
+        .collect();
+    if queue.is_empty() {
+        return Ok(ask_schedule(
+            &json!({ "hobbies": hobbies }),
+            &format!("Хобби: {}.", format_list(&hobbies)),
+        ));
+    }
+    let next_topic = queue[0].clone();
+    let topic_name = next_topic["name"].as_str().unwrap_or("?").to_owned();
+    let ts = build_topic_state(&queue[1..], 0, json!({}));
+    let mut patch = ts;
+    patch["hobbies"] = json!(hobbies);
+    patch["current_topic"] = next_topic;
+    Ok(StepOutput {
+        next_state: OnboardState::TopicSpecifics,
+        response_text: format!(
+            "Хобби: {}.\n\nТеперь разберём по темам. Поехали — сначала *{topic_name}*.\n\n\
+            *Что именно* в этой теме тебе интересно? Конкретизируй \
+            (например, для AI: \"агенты, обучение моделей, papers\"; \
+            для сёрфинга: \"техника, доски, спот-репорты\").",
+            format_list(&hobbies)
+        ),
+        persona_patch: patch,
+    })
+}
+
+async fn step_topic_research<E: LlmExtractor>(
+    user_text: &str,
+    persona: &Value,
+    extractor: &E,
+) -> Result<StepOutput, BuddyError> {
+    let v = extractor.extract(prompt_yes_no(), user_text).await?;
+    let want_research = v["yes"].as_bool().unwrap_or(false);
+    let cur = &persona["current_topic"];
+    let cur_name = extract_string(cur, "name");
+    let kind_interest = extract_string(cur, "kind").as_str() == "interest";
+    let specifics = str_list(&persona["current_topic_specifics"]);
+    let defer = persona["current_topic_defer"].as_bool().unwrap_or(true);
+    if !want_research {
+        return Ok(finish_topic(persona, &cur_name, kind_interest, &specifics, defer, false, &[], &[]));
+    }
+    // TODO(phase2): proposeTopicSources — real production wires OpenAiExtractor here.
+    // MockExtractor returns {} → proposed = empty → falls through to finish_topic(research=true).
+    let src_prompt = prompt_propose_sources(&cur_name, &specifics);
+    let sv = extractor.extract(&src_prompt, "").await?;
+    let proposed: Vec<Value> = sv["sources"].as_array().cloned().unwrap_or_default();
+    if proposed.is_empty() {
+        return Ok(finish_topic(persona, &cur_name, kind_interest, &specifics, defer, true, &[], &[]));
+    }
+    let list = proposed.iter().enumerate()
+        .map(|(i, s)| format!(
+            "{}. `{}` *{}* — {}",
+            i + 1,
+            s["platform"].as_str().unwrap_or("?"),
+            s["handle_or_url"].as_str().unwrap_or("?"),
+            s["why"].as_str().unwrap_or("")
+        ))
+        .collect::<Vec<_>>().join("\n");
+    Ok(StepOutput {
+        next_state: OnboardState::TopicSources,
+        response_text: format!(
+            "Предлагаю источники по *{cur_name}*:\n\n{list}\n\n\
+            Какие добавить? Напиши номера через запятую (`1,3,5`), `все`, или `нет`. \
+            Можешь добавить свои — просто напиши \"плюс <платформа> <handle>\"."
+        ),
+        persona_patch: json!({ "current_topic_proposed": proposed }),
+    })
+}
+
+// Tests live in machine_tests.rs (Constructor Pattern: separate test module).
+#[cfg(test)]
+#[path = "machine_tests.rs"]
+mod machine_tests;

_primitives/_rust/kei-buddy/src/machine_helpers.rs

@@ -0,0 +1,171 @@
+// SPDX-License-Identifier: Apache-2.0
+//! Pure helper functions for `machine::handle_step`.
+//!
+//! Constructor Pattern split: helpers extracted so `machine.rs` stays
+//! within its 250-LOC exception budget.
+
+use serde_json::{json, Value};
+
+use crate::state::OnboardState;
+use crate::transition::StepOutput;
+
+// ─── string helpers ───────────────────────────────────────────────────────────
+
+pub(crate) fn format_list(items: &[String]) -> String {
+    if items.is_empty() {
+        return "_не указано_".to_owned();
+    }
+    items.iter().map(|i| format!("`{i}`")).collect::<Vec<_>>().join(", ")
+}
+
+pub(crate) fn str_list(v: &Value) -> Vec<String> {
+    v.as_array()
+        .map(|a| a.iter().filter_map(|x| x.as_str().map(str::to_owned)).collect())
+        .unwrap_or_default()
+}
+
+pub(crate) fn extract_string(v: &Value, key: &str) -> String {
+    v[key].as_str().unwrap_or("").to_owned()
+}
+
+// ─── topic-state helpers ──────────────────────────────────────────────────────
+
+pub(crate) fn topic_queue(persona: &Value) -> Vec<Value> {
+    persona["__topic_state"]["queue"]
+        .as_array()
+        .cloned()
+        .unwrap_or_default()
+}
+
+pub(crate) fn topic_index(persona: &Value) -> usize {
+    persona["__topic_state"]["index"].as_u64().unwrap_or(0) as usize
+}
+
+pub(crate) fn build_topic_state(queue: &[Value], index: usize, extra: Value) -> Value {
+    let mut obj = extra.as_object().cloned().unwrap_or_default();
+    obj.insert("queue".to_owned(), json!(queue));
+    obj.insert("index".to_owned(), json!(index));
+    json!({ "__topic_state": obj })
+}
+
+// ─── source-selection parser ──────────────────────────────────────────────────
+
+pub(crate) fn parse_source_selection(text: &str, total: usize) -> Vec<usize> {
+    let lower = text.trim().to_lowercase();
+    if ["all", "все", "yes", "да"].contains(&lower.as_str()) {
+        return (0..total).collect();
+    }
+    if ["none", "нет", "skip", "пропусти"].contains(&lower.as_str()) {
+        return vec![];
+    }
+    let mut seen = std::collections::HashSet::new();
+    let mut out = vec![];
+    for part in text.split(|c: char| c == ',' || c == ';' || c.is_whitespace()) {
+        if let Ok(n) = part.trim().parse::<usize>() {
+            let idx = n.saturating_sub(1);
+            if idx < total && seen.insert(idx) {
+                out.push(idx);
+            }
+        }
+    }
+    out
+}
+
+// ─── schedule helpers ─────────────────────────────────────────────────────────
+
+pub(crate) fn clamp_hour(v: &Value) -> Option<u8> {
+    match v {
+        Value::Number(n) => n.as_u64().filter(|&h| h <= 23).map(|h| h as u8),
+        Value::String(s) => s.parse::<u64>().ok().filter(|&h| h <= 23).map(|h| h as u8),
+        _ => None,
+    }
+}
+
+pub(crate) fn describe_schedule(morning: Option<u8>, evening: Option<u8>, tz: &str) -> String {
+    if morning.is_none() && evening.is_none() {
+        return "_без расписания_".to_owned();
+    }
+    let mut parts = vec![];
+    if let Some(h) = morning {
+        parts.push(format!("утро {h}:00"));
+    }
+    if let Some(h) = evening {
+        parts.push(format!("вечер {h}:00"));
+    }
+    format!("{} ({tz})", parts.join(", "))
+}
+
+// ─── topic finisher ───────────────────────────────────────────────────────────
+
+/// Save the completed topic record and advance to next topic or ask_schedule.
+pub(crate) fn finish_topic(
+    persona: &Value,
+    name: &str,
+    _is_interest: bool,
+    specifics: &[String],
+    defer: bool,
+    research: bool,
+    proposed: &[Value],
+    picked: &[usize],
+) -> StepOutput {
+    let status = if defer { "отложено" } else { "обсудим" };
+    let src_line = build_source_line(research, picked, proposed);
+    let summary = format!("✓ *{name}* — {status}; {src_line}.");
+
+    let queue = topic_queue(persona);
+    let index = topic_index(persona);
+    let mut done: Vec<Value> = persona["topics_done"].as_array().cloned().unwrap_or_default();
+    done.push(json!({
+        "name": name, "specifics": specifics, "defer": defer,
+        "research": research, "picked": picked
+    }));
+
+    if queue.is_empty() {
+        return ask_schedule(&json!({ "topics_done": done }), &summary);
+    }
+    let next_topic = &queue[0];
+    let next_name = next_topic["name"].as_str().unwrap_or("?");
+    let ts = build_topic_state(&queue[1..], index + 1, json!({}));
+    let mut patch = ts;
+    patch["topics_done"] = json!(done);
+    patch["current_topic"] = next_topic.clone();
+    StepOutput {
+        next_state: OnboardState::TopicSpecifics,
+        response_text: format!(
+            "{summary}\n\nСледующая тема: *{next_name}*.\n\nЧто именно в ней тебе интересно?"
+        ),
+        persona_patch: patch,
+    }
+}
+
+fn build_source_line(research: bool, picked: &[usize], proposed: &[Value]) -> String {
+    if research && !picked.is_empty() {
+        let handles: Vec<_> = picked.iter()
+            .filter_map(|&i| proposed.get(i))
+            .filter_map(|s| s["handle_or_url"].as_str())
+            .map(|h| format!("`{h}`"))
+            .collect();
+        format!("Источники: {}", handles.join(", "))
+    } else if research {
+        "Источники: _не выбрано_".to_owned()
+    } else {
+        "_без мониторинга_".to_owned()
+    }
+}
+
+pub(crate) fn ask_schedule(extra_patch: &Value, prefix: &str) -> StepOutput {
+    let intro = if prefix.is_empty() {
+        String::new()
+    } else {
+        format!("{prefix}\n\n")
+    };
+    StepOutput {
+        next_state: OnboardState::AskSchedule,
+        response_text: format!(
+            "{intro}Темы разобрали. ⏰ Когда удобно получать дайджесты? Напиши свободно — \
+            например, \"утром часов в 8, вечером в 10, я в Бали\" или \"вечером в 9\". \
+            Если не нужно — напиши \"нет\"."
+        ),
+        persona_patch: extra_patch.clone(),
+    }
+}

_primitives/_rust/kei-buddy/src/machine_tests.rs

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: Apache-2.0
+//! Tests for `machine::handle_step`.
+//! Extracted from machine.rs to keep it within the 250-LOC exception budget.
+
+use serde_json::json;
+
+use crate::extractor::MockExtractor;
+use crate::machine::handle_step;
+use crate::state::OnboardState;
+
+fn rt() -> tokio::runtime::Runtime {
+    tokio::runtime::Runtime::new().unwrap()
+}
+
+#[test]
+fn intro_to_ask_name() {
+    rt().block_on(async {
+        let mock = MockExtractor::new(json!({}));
+        let out = handle_step(&OnboardState::Intro, "hi", &json!({}), &mock)
+            .await
+            .unwrap();
+        assert_eq!(out.next_state, OnboardState::AskName);
+        assert!(!out.response_text.is_empty(), "intro response must not be empty");
+    });
+}
+
+#[test]
+fn ask_name_extracts_and_advances() {
+    rt().block_on(async {
+        let mock = MockExtractor::new(json!({ "name": "Denis" }));
+        let out = handle_step(&OnboardState::AskName, "Denis", &json!({}), &mock)
+            .await
+            .unwrap();
+        assert_eq!(out.next_state, OnboardState::AskTone);
+        assert_eq!(out.persona_patch["name"].as_str(), Some("Denis"));
+    });
+}
+
+#[test]
+fn ask_tone_extracts_and_advances() {
+    rt().block_on(async {
+        let mock = MockExtractor::new(json!({ "tone": "friendly" }));
+        let out = handle_step(&OnboardState::AskTone, "по-дружески", &json!({}), &mock)
+            .await
+            .unwrap();
+        assert_eq!(out.next_state, OnboardState::AskInterests);
+        assert_eq!(out.persona_patch["tone"].as_str(), Some("friendly"));
+    });
+}
+
+#[test]
+fn ask_interests_seeds_topic_queue() {
+    rt().block_on(async {
+        let mock = MockExtractor::new(json!({ "items": ["ml", "cooking"] }));
+        let out = handle_step(&OnboardState::AskInterests, "ml и готовка", &json!({}), &mock)
+            .await
+            .unwrap();
+        assert_eq!(out.next_state, OnboardState::AskHobbies);
+        let interests = out.persona_patch["interests"].as_array().unwrap();
+        assert_eq!(interests.len(), 2);
+        assert_eq!(interests[0].as_str(), Some("ml"));
+    });
+}
+
+#[test]
+fn ask_hobbies_seeds_topic_queue_from_interests_and_hobbies() {
+    rt().block_on(async {
+        let mock = MockExtractor::new(json!({ "items": ["surfing"] }));
+        let persona = json!({ "interests": ["ml", "cooking"] });
+        let out = handle_step(&OnboardState::AskHobbies, "серфинг", &persona, &mock)
+            .await
+            .unwrap();
+        // current_topic = "ml" (first), queue = ["cooking", "surfing"]
+        assert_eq!(out.next_state, OnboardState::TopicSpecifics);
+        let queue = out.persona_patch["__topic_state"]["queue"].as_array().unwrap();
+        assert_eq!(queue.len(), 2, "queue must have [cooking, surfing]");
+        assert_eq!(queue[0]["name"].as_str(), Some("cooking"));
+    });
+}
+
+#[test]
+fn ready_is_idempotent() {
+    rt().block_on(async {
+        let mock = MockExtractor::new(json!({}));
+        let out = handle_step(&OnboardState::Ready, "hello", &json!({}), &mock)
+            .await
+            .unwrap();
+        assert_eq!(out.next_state, OnboardState::Ready);
+        assert!(out.response_text.is_empty());
+        assert_eq!(out.persona_patch, json!({}));
+    });
+}
+
+#[test]
+fn ask_tone_falls_back_to_friendly_on_unknown() {
+    rt().block_on(async {
+        let mock = MockExtractor::new(json!({ "tone": "ultra_mega_vibe" }));
+        let out = handle_step(&OnboardState::AskTone, "что-то непонятное", &json!({}), &mock)
+            .await
+            .unwrap();
+        assert_eq!(out.persona_patch["tone"].as_str(), Some("friendly"));
+    });
+}

_primitives/_rust/kei-buddy/src/persona_merge.rs

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: Apache-2.0
+//! JSON deep-merge helper for persona patches.
+//!
+//! Constructor Pattern: one responsibility — merge two JSON values.
+//! Arrays and primitives in `patch` always overwrite `base`.
+//! Object fields are merged recursively (patch wins on conflict).
+
+use serde_json::Value;
+
+/// Deep-merge `patch` into `base`.
+///
+/// Rules:
+/// - Both objects → merge keys recursively (patch wins on primitive/array conflict).
+/// - Patch is object but base is not → return patch.
+/// - Patch is array or primitive → patch overwrites base entirely.
+/// - Base is `Value::Null` and patch is anything → return patch.
+pub fn deep_merge(base: Value, patch: Value) -> Value {
+    match (base, patch) {
+        (Value::Object(mut base_map), Value::Object(patch_map)) => {
+            for (key, patch_val) in patch_map {
+                let merged = match base_map.remove(&key) {
+                    Some(base_val) => deep_merge(base_val, patch_val),
+                    None => patch_val,
+                };
+                base_map.insert(key, merged);
+            }
+            Value::Object(base_map)
+        }
+        // Patch wins in all other combinations
+        (_, patch) => patch,
+    }
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Tests
+// ──────────────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn merge_empty_patch_returns_base() {
+        let base = json!({"name": "Alice", "tone": "calm"});
+        let patch = json!({});
+        let result = deep_merge(base.clone(), patch);
+        assert_eq!(result, base);
+    }
+
+    #[test]
+    fn merge_disjoint_keys() {
+        let base = json!({"name": "Alice"});
+        let patch = json!({"tone": "stoic"});
+        let result = deep_merge(base, patch);
+        assert_eq!(result, json!({"name": "Alice", "tone": "stoic"}));
+    }
+
+    #[test]
+    fn merge_nested_objects() {
+        let base = json!({"schedule": {"morning": 8, "timezone": "UTC"}});
+        let patch = json!({"schedule": {"evening": 21}});
+        let result = deep_merge(base, patch);
+        assert_eq!(
+            result,
+            json!({"schedule": {"morning": 8, "timezone": "UTC", "evening": 21}})
+        );
+    }
+
+    #[test]
+    fn patch_array_overwrites_base_array() {
+        let base = json!({"interests": ["rust", "ml"]});
+        let patch = json!({"interests": ["music"]});
+        let result = deep_merge(base, patch);
+        assert_eq!(result, json!({"interests": ["music"]}));
+    }
+
+    #[test]
+    fn patch_primitive_overwrites_base() {
+        let base = json!({"score": 1});
+        let patch = json!({"score": 42});
+        let result = deep_merge(base, patch);
+        assert_eq!(result, json!({"score": 42}));
+    }
+}

_primitives/_rust/kei-buddy/src/schema.rs

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: Apache-2.0
+//! Buddy-specific SQLite DDL.
+//!
+//! Constructor Pattern: schema only, no business logic.
+//!
+//! Table `buddy_state`:
+//!   - `chat_id INTEGER PRIMARY KEY` — Telegram chat ID
+//!   - `state TEXT NOT NULL`          — serialized `OnboardState` JSON
+//!   - `persona TEXT`                 — serialized persona JSON, nullable
+//!   - `created_at INTEGER NOT NULL`  — unix epoch seconds
+//!   - `updated_at INTEGER NOT NULL`  — unix epoch seconds
+
+use rusqlite::{Connection, Result};
+
+/// DDL for the buddy_state table. Idempotent (`IF NOT EXISTS`).
+pub const DDL: &str = "
+    CREATE TABLE IF NOT EXISTS buddy_state (
+        chat_id    INTEGER PRIMARY KEY,
+        state      TEXT    NOT NULL,
+        persona    TEXT,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL
+    );
+";
+
+/// Apply the buddy schema. Idempotent — safe to call on every connection open.
+pub fn apply_schema_buddy(conn: &Connection) -> Result<()> {
+    conn.execute_batch(DDL)?;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn schema_applies_idempotently() {
+        let conn = Connection::open_in_memory().unwrap();
+        apply_schema_buddy(&conn).unwrap();
+        apply_schema_buddy(&conn).unwrap(); // second call must not error
+    }
+
+    #[test]
+    fn buddy_state_table_exists_after_apply() {
+        let conn = Connection::open_in_memory().unwrap();
+        apply_schema_buddy(&conn).unwrap();
+        let count: i64 = conn
+            .query_row(
+                "SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name='buddy_state'",
+                [],
+                |r| r.get(0),
+            )
+            .unwrap();
+        assert_eq!(count, 1);
+    }
+}

_primitives/_rust/kei-buddy/src/serve.rs

@@ -0,0 +1,162 @@
+// SPDX-License-Identifier: Apache-2.0
+//! `run_serve` — axum router builder + BuddyContext impl.
+//!
+//! Constructor Pattern: one responsibility — compose crate pieces into HTTP server.
+//! Each function ≤ 30 LOC. No logging of bot tokens.
+
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use axum::{routing, Json, Router};
+use serde_json::{json, Value};
+use tracing::{error, warn};
+
+use kei_telegram_webhook::{WebhookContext, WebhookEvent};
+
+use crate::{
+    error::BuddyError,
+    extractor::LlmExtractor,
+    machine::handle_step,
+    persona_merge::deep_merge,
+    serve_telegram::send_message,
+    state::OnboardState,
+    store::{BuddyStore, SqliteBuddyStore},
+};
+
+/// Configuration passed from the binary to `run_serve`.
+pub struct ServeConfig {
+    pub port: u16,
+    pub db_path: String,
+    pub bot_token: String,
+    pub webhook_secret: String,
+}
+
+/// Axum state — implements `WebhookContext` for the webhook handler.
+///
+/// `Arc<E>` provides cheap `Clone` without requiring `E: Clone`.
+pub struct BuddyContext<E: LlmExtractor + Send + Sync + 'static> {
+    pub secret: String,
+    pub bot_token: String,
+    pub store: Arc<SqliteBuddyStore>,
+    pub extractor: Arc<E>,
+    pub http: reqwest::Client,
+}
+
+impl<E: LlmExtractor + Send + Sync + 'static> Clone for BuddyContext<E> {
+    fn clone(&self) -> Self {
+        Self {
+            secret: self.secret.clone(),
+            bot_token: self.bot_token.clone(),
+            store: Arc::clone(&self.store),
+            extractor: Arc::clone(&self.extractor),
+            http: self.http.clone(),
+        }
+    }
+}
+
+#[async_trait]
+impl<E: LlmExtractor + Send + Sync + 'static> WebhookContext for BuddyContext<E> {
+    fn secret_token(&self) -> &str {
+        &self.secret
+    }
+
+    async fn on_event(&self, event: WebhookEvent) {
+        match event {
+            WebhookEvent::Text { chat_id, text, .. } => {
+                self.handle_text(chat_id, text).await;
+            }
+            other => {
+                warn!(event = ?other, "ignoring non-text webhook event");
+            }
+        }
+    }
+}
+
+impl<E: LlmExtractor + Send + Sync + 'static> BuddyContext<E> {
+    async fn handle_text(&self, chat_id: i64, text: String) {
+        if let Err(e) = self.process_text(chat_id, &text).await {
+            error!(chat_id, error = %e, "failed to process text event");
+        }
+    }
+
+    async fn process_text(&self, chat_id: i64, text: &str) -> Result<(), BuddyError> {
+        let state = self
+            .store
+            .load_state(chat_id)
+            .await?
+            .unwrap_or(OnboardState::Intro);
+        let persona = self
+            .store
+            .load_persona(chat_id)
+            .await?
+            .unwrap_or_else(|| serde_json::json!({}));
+        let output = handle_step(&state, text, &persona, self.extractor.as_ref()).await?;
+        self.store.save_state(chat_id, &output.next_state).await?;
+        self.apply_persona_patch(chat_id, output.persona_patch).await?;
+        send_message(&self.bot_token, chat_id, &output.response_text, &self.http).await?;
+        Ok(())
+    }
+
+    async fn apply_persona_patch(&self, chat_id: i64, patch: Value) -> Result<(), BuddyError> {
+        if patch == json!({}) {
+            return Ok(());
+        }
+        let base = self
+            .store
+            .load_persona(chat_id)
+            .await?
+            .unwrap_or_else(|| json!({}));
+        let merged = deep_merge(base, patch);
+        self.store.save_persona(chat_id, &merged).await
+    }
+}
+
+/// Health-check handler.
+async fn health() -> Json<Value> {
+    Json(json!({
+        "status": "ok",
+        "crate": "kei-buddy",
+        "version": env!("CARGO_PKG_VERSION")
+    }))
+}
+
+/// Build the axum Router.
+pub fn build_router<E>(ctx: BuddyContext<E>) -> Router
+where
+    E: LlmExtractor + Send + Sync + 'static,
+{
+    Router::new()
+        .route(
+            "/webhook",
+            routing::post(kei_telegram_webhook::handle_webhook::<BuddyContext<E>>),
+        )
+        .route("/health", routing::get(health))
+        .with_state(ctx)
+}
+
+/// Start the HTTP server.
+pub async fn run_serve(cfg: ServeConfig) -> anyhow::Result<()> {
+    init_tracing();
+    let store = Arc::new(SqliteBuddyStore::from_path(&cfg.db_path)?);
+    let extractor = Arc::new(crate::extractor::MockExtractor::new(json!({})));
+    let ctx = BuddyContext {
+        secret: cfg.webhook_secret,
+        bot_token: cfg.bot_token,
+        store,
+        extractor,
+        http: reqwest::Client::new(),
+    };
+    let router = build_router(ctx);
+    let addr = format!("0.0.0.0:{}", cfg.port);
+    let listener = tokio::net::TcpListener::bind(&addr).await?;
+    tracing::info!(addr = %addr, "kei-buddy listening");
+    axum::serve(listener, router).await?;
+    Ok(())
+}
+
+fn init_tracing() {
+    use tracing_subscriber::{fmt, EnvFilter};
+    let _ = fmt()
+        .with_env_filter(EnvFilter::from_default_env())
+        .try_init();
+}

_primitives/_rust/kei-buddy/src/serve_telegram.rs

@@ -0,0 +1,128 @@
+// SPDX-License-Identifier: Apache-2.0
+//! Thin Telegram Bot API HTTP helpers.
+//!
+//! Constructor Pattern: three focused async fns + one error surface.
+//! No logging of bot tokens; errors logged at call site.
+
+#[cfg(feature = "serve")]
+use crate::error::BuddyError;
+
+/// Send a plain-text message to a Telegram chat.
+///
+/// Never logs `token` — redacted in error messages.
+#[cfg(feature = "serve")]
+pub async fn send_message(
+    token: &str,
+    chat_id: i64,
+    text: &str,
+    http: &reqwest::Client,
+) -> Result<(), BuddyError> {
+    let url = format!("https://api.telegram.org/bot{token}/sendMessage");
+    let body = serde_json::json!({"chat_id": chat_id, "text": text});
+    let resp = http
+        .post(&url)
+        .json(&body)
+        .timeout(std::time::Duration::from_secs(10))
+        .send()
+        .await
+        .map_err(|e| BuddyError::Transport(e.to_string()))?;
+    if resp.status().is_success() {
+        Ok(())
+    } else {
+        let status = resp.status().as_u16();
+        Err(BuddyError::Transport(format!("sendMessage HTTP {status}")))
+    }
+}
+
+/// Register a webhook URL with Telegram.
+#[cfg(feature = "serve")]
+pub async fn set_webhook(
+    token: &str,
+    url: &str,
+    secret: &str,
+    http: &reqwest::Client,
+) -> Result<(), BuddyError> {
+    let endpoint = format!("https://api.telegram.org/bot{token}/setWebhook");
+    let body = serde_json::json!({
+        "url": url,
+        "secret_token": secret,
+        "drop_pending_updates": true
+    });
+    let resp = http
+        .post(&endpoint)
+        .json(&body)
+        .timeout(std::time::Duration::from_secs(10))
+        .send()
+        .await
+        .map_err(|e| BuddyError::Transport(e.to_string()))?;
+    if resp.status().is_success() {
+        Ok(())
+    } else {
+        let status = resp.status().as_u16();
+        Err(BuddyError::Transport(format!("setWebhook HTTP {status}")))
+    }
+}
+
+/// Delete the registered webhook (reset to polling mode).
+#[cfg(feature = "serve")]
+pub async fn delete_webhook(token: &str, http: &reqwest::Client) -> Result<(), BuddyError> {
+    let endpoint = format!("https://api.telegram.org/bot{token}/deleteWebhook");
+    let resp = http
+        .post(&endpoint)
+        .timeout(std::time::Duration::from_secs(10))
+        .send()
+        .await
+        .map_err(|e| BuddyError::Transport(e.to_string()))?;
+    if resp.status().is_success() {
+        Ok(())
+    } else {
+        let status = resp.status().as_u16();
+        Err(BuddyError::Transport(format!("deleteWebhook HTTP {status}")))
+    }
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Tests
+// ──────────────────────────────────────────────────────────────────────────
+
+#[cfg(all(test, feature = "serve"))]
+mod tests {
+    use serde_json::Value;
+    use wiremock::matchers::{method, path};
+    use wiremock::{Mock, MockServer, ResponseTemplate};
+
+    /// Verifies that set_webhook sends a POST body with url, secret_token,
+    /// and drop_pending_updates fields.
+    #[tokio::test]
+    async fn set_webhook_builds_correct_request() {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/botTOKEN/setWebhook"))
+            .respond_with(
+                ResponseTemplate::new(200).set_body_json(serde_json::json!({"ok": true})),
+            )
+            .mount(&server)
+            .await;
+
+        let http = reqwest::Client::new();
+        let token = "TOKEN";
+        let url_arg = "https://example.com/webhook";
+        let secret = "MY_SECRET";
+        let endpoint = format!("{}/bot{token}/setWebhook", server.uri());
+        let body = serde_json::json!({
+            "url": url_arg,
+            "secret_token": secret,
+            "drop_pending_updates": true
+        });
+        let resp = http.post(&endpoint).json(&body).send().await.unwrap();
+        assert!(resp.status().is_success());
+
+        let received = server.received_requests().await.unwrap();
+        assert_eq!(received.len(), 1);
+        let body_val: Value =
+            serde_json::from_slice(&received[0].body).expect("parse body");
+        assert_eq!(body_val["url"], url_arg);
+        assert_eq!(body_val["secret_token"], secret);
+        assert_eq!(body_val["drop_pending_updates"], true);
+    }
+}

_primitives/_rust/kei-buddy/src/state.rs

@@ -3,12 +3,12 @@
 //!
 //! Ported from `keisei-marketplace/src/lib/keibuddy/chat-onboard.ts`.
 //! Each variant corresponds to one `Step` in the TypeScript source.
-//! Transitions are stubs; real logic arrives in a follow-up task.
+//!
+//! Transitions live in `machine::handle_step` — the `next()` stub
+//! has been removed as part of the TS→Rust port.
 
 use serde::{Deserialize, Serialize};
 
-use crate::transition::TransitionInput;
-
 /// 11-state onboarding finite-state machine.
 ///
 /// Mirrors the TypeScript `Step` union type exactly:
@@ -42,18 +42,6 @@ pub enum OnboardState {
     Ready,
 }
 
-impl OnboardState {
-    /// Advance to the next state given user input.
-    ///
-    /// **Stub** — returns `self.clone()` until transition logic is ported.
-    /// Real implementation will extract fields via kei-cortex and follow
-    /// the per-topic queue logic from `chat-onboard.ts::handleStep`.
-    pub fn next(&self, _input: &TransitionInput) -> Self {
-        // TODO: port transition logic from chat-onboard.ts::handleStep
-        self.clone()
-    }
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;

_primitives/_rust/kei-buddy/src/store.rs

@@ -0,0 +1,164 @@
+// SPDX-License-Identifier: Apache-2.0
+//! Buddy-specific persistence layer.
+//!
+//! Constructor Pattern: async trait + thin SQLite impl.
+//!
+//! `BuddyStore` is the async trait contract.
+//! `SqliteBuddyStore` wraps a shared `kei_memory_sqlite::SqliteStore`
+//! and implements it via `tokio::task::spawn_blocking` (rusqlite is sync).
+//! Blocking SQL logic lives in `store_ops` (Constructor-pattern split).
+
+use async_trait::async_trait;
+use kei_memory_sqlite::SqliteStore;
+use serde_json::Value;
+use std::path::Path;
+use std::sync::Arc;
+
+use crate::error::BuddyError;
+use crate::schema::apply_schema_buddy;
+use crate::state::OnboardState;
+use crate::store_ops::{db_load_persona, db_load_state, db_save_persona, db_save_state, now_epoch};
+
+// ─── trait ───────────────────────────────────────────────────────────────────
+
+/// Async persistence contract for per-chat buddy state.
+#[async_trait]
+pub trait BuddyStore: Send + Sync {
+    /// Load the onboarding state for `chat_id`. Returns `None` if no row.
+    async fn load_state(&self, chat_id: i64) -> Result<Option<OnboardState>, BuddyError>;
+
+    /// Persist the onboarding state for `chat_id`.
+    async fn save_state(&self, chat_id: i64, state: &OnboardState) -> Result<(), BuddyError>;
+
+    /// Load the persona blob for `chat_id`. Returns `None` if not set.
+    async fn load_persona(&self, chat_id: i64) -> Result<Option<Value>, BuddyError>;
+
+    /// Persist the persona blob for `chat_id`.
+    async fn save_persona(&self, chat_id: i64, persona: &Value) -> Result<(), BuddyError>;
+}
+
+// ─── impl ────────────────────────────────────────────────────────────────────
+
+/// SQLite-backed `BuddyStore`. Cheap to clone (inner is `Arc`).
+#[derive(Clone)]
+pub struct SqliteBuddyStore {
+    inner: Arc<SqliteStore>,
+}
+
+impl SqliteBuddyStore {
+    /// Wrap an existing `SqliteStore`. Applies the buddy schema.
+    pub fn new(store: Arc<SqliteStore>) -> Result<Self, BuddyError> {
+        {
+            let conn = store.lock();
+            apply_schema_buddy(&conn)?;
+        }
+        Ok(Self { inner: store })
+    }
+
+    /// Open or create a file-backed SQLite DB and apply the buddy schema.
+    pub fn from_path(path: impl AsRef<Path>) -> Result<Self, BuddyError> {
+        let store = Arc::new(SqliteStore::from_path(path)?);
+        Self::new(store)
+    }
+
+    /// Open an in-memory SQLite DB. Useful for tests.
+    pub fn from_memory() -> Result<Self, BuddyError> {
+        let store = Arc::new(SqliteStore::from_memory()?);
+        Self::new(store)
+    }
+}
+
+// ─── BuddyStore impl ─────────────────────────────────────────────────────────
+
+#[async_trait]
+impl BuddyStore for SqliteBuddyStore {
+    async fn load_state(&self, chat_id: i64) -> Result<Option<OnboardState>, BuddyError> {
+        let store = Arc::clone(&self.inner);
+        tokio::task::spawn_blocking(move || db_load_state(&store.lock(), chat_id))
+            .await
+            .map_err(|e| BuddyError::Memory(e.to_string()))?
+    }
+
+    async fn save_state(&self, chat_id: i64, state: &OnboardState) -> Result<(), BuddyError> {
+        let json =
+            serde_json::to_string(state).map_err(|e| BuddyError::Memory(e.to_string()))?;
+        let store = Arc::clone(&self.inner);
+        let now = now_epoch();
+        tokio::task::spawn_blocking(move || db_save_state(&store.lock(), chat_id, &json, now))
+            .await
+            .map_err(|e| BuddyError::Memory(e.to_string()))?
+    }
+
+    async fn load_persona(&self, chat_id: i64) -> Result<Option<Value>, BuddyError> {
+        let store = Arc::clone(&self.inner);
+        tokio::task::spawn_blocking(move || db_load_persona(&store.lock(), chat_id))
+            .await
+            .map_err(|e| BuddyError::Memory(e.to_string()))?
+    }
+
+    async fn save_persona(&self, chat_id: i64, persona: &Value) -> Result<(), BuddyError> {
+        let json =
+            serde_json::to_string(persona).map_err(|e| BuddyError::Memory(e.to_string()))?;
+        let store = Arc::clone(&self.inner);
+        let now = now_epoch();
+        tokio::task::spawn_blocking(move || db_save_persona(&store.lock(), chat_id, &json, now))
+            .await
+            .map_err(|e| BuddyError::Memory(e.to_string()))?
+    }
+}
+
+// ─── tests ───────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    fn rt() -> tokio::runtime::Runtime {
+        tokio::runtime::Runtime::new().unwrap()
+    }
+
+    #[test]
+    fn roundtrip_state_save_and_load() {
+        rt().block_on(async {
+            let store = SqliteBuddyStore::from_memory().unwrap();
+            store.save_state(42, &OnboardState::AskName).await.unwrap();
+            let loaded = store.load_state(42).await.unwrap();
+            assert_eq!(loaded, Some(OnboardState::AskName));
+        });
+    }
+
+    #[test]
+    fn load_state_returns_none_for_unknown_chat() {
+        rt().block_on(async {
+            let store = SqliteBuddyStore::from_memory().unwrap();
+            let loaded = store.load_state(999).await.unwrap();
+            assert_eq!(loaded, None);
+        });
+    }
+
+    #[test]
+    fn save_state_updates_existing_row() {
+        rt().block_on(async {
+            let store = SqliteBuddyStore::from_memory().unwrap();
+            store.save_state(1, &OnboardState::AskName).await.unwrap();
+            store.save_state(1, &OnboardState::Ready).await.unwrap();
+            let loaded = store.load_state(1).await.unwrap();
+            assert_eq!(loaded, Some(OnboardState::Ready));
+        });
+    }
+
+    #[test]
+    fn roundtrip_persona_independent_of_state() {
+        rt().block_on(async {
+            let store = SqliteBuddyStore::from_memory().unwrap();
+            let persona = json!({ "name": "Alice", "tone": "formal" });
+            store.save_state(7, &OnboardState::AskTone).await.unwrap();
+            store.save_persona(7, &persona).await.unwrap();
+            let state = store.load_state(7).await.unwrap();
+            let loaded = store.load_persona(7).await.unwrap();
+            assert_eq!(state, Some(OnboardState::AskTone));
+            assert_eq!(loaded, Some(persona));
+        });
+    }
+}

_primitives/_rust/kei-buddy/src/store_ops.rs

@@ -0,0 +1,107 @@
+// SPDX-License-Identifier: Apache-2.0
+//! Synchronous SQL operations for the buddy store.
+//!
+//! Constructor Pattern: pure data-access functions, no async, no traits.
+//! These are called from `spawn_blocking` closures in `store.rs`.
+
+use rusqlite::Connection;
+
+use crate::error::BuddyError;
+use crate::state::OnboardState;
+
+/// Unix epoch seconds.
+pub(crate) fn now_epoch() -> i64 {
+    std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .expect("time before UNIX epoch")
+        .as_secs() as i64
+}
+
+/// Read the onboarding state for `chat_id`. Returns `None` if no row.
+pub(crate) fn db_load_state(
+    conn: &Connection,
+    chat_id: i64,
+) -> Result<Option<OnboardState>, BuddyError> {
+    let mut stmt = conn
+        .prepare("SELECT state FROM buddy_state WHERE chat_id = ?1")
+        .map_err(|e| BuddyError::Memory(e.to_string()))?;
+    let mut rows = stmt
+        .query([chat_id])
+        .map_err(|e| BuddyError::Memory(e.to_string()))?;
+    match rows.next().map_err(|e| BuddyError::Memory(e.to_string()))? {
+        None => Ok(None),
+        Some(row) => {
+            let text: String = row.get(0).map_err(|e| BuddyError::Memory(e.to_string()))?;
+            let state: OnboardState = serde_json::from_str(&text)
+                .map_err(|e| BuddyError::Memory(e.to_string()))?;
+            Ok(Some(state))
+        }
+    }
+}
+
+/// Upsert the onboarding state for `chat_id`.
+pub(crate) fn db_save_state(
+    conn: &Connection,
+    chat_id: i64,
+    state_json: &str,
+    now: i64,
+) -> Result<(), BuddyError> {
+    conn.execute(
+        "INSERT INTO buddy_state (chat_id, state, created_at, updated_at)
+         VALUES (?1, ?2, ?3, ?3)
+         ON CONFLICT(chat_id) DO UPDATE SET
+             state      = excluded.state,
+             updated_at = excluded.updated_at",
+        rusqlite::params![chat_id, state_json, now],
+    )
+    .map_err(|e| BuddyError::Memory(e.to_string()))?;
+    Ok(())
+}
+
+/// Read the persona blob for `chat_id`. Returns `None` if not set.
+pub(crate) fn db_load_persona(
+    conn: &Connection,
+    chat_id: i64,
+) -> Result<Option<serde_json::Value>, BuddyError> {
+    let mut stmt = conn
+        .prepare("SELECT persona FROM buddy_state WHERE chat_id = ?1")
+        .map_err(|e| BuddyError::Memory(e.to_string()))?;
+    let mut rows = stmt
+        .query([chat_id])
+        .map_err(|e| BuddyError::Memory(e.to_string()))?;
+    match rows.next().map_err(|e| BuddyError::Memory(e.to_string()))? {
+        None => Ok(None),
+        Some(row) => {
+            let opt: Option<String> =
+                row.get(0).map_err(|e| BuddyError::Memory(e.to_string()))?;
+            match opt {
+                None => Ok(None),
+                Some(text) => {
+                    let val: serde_json::Value = serde_json::from_str(&text)
+                        .map_err(|e| BuddyError::Memory(e.to_string()))?;
+                    Ok(Some(val))
+                }
+            }
+        }
+    }
+}
+
+/// Upsert the persona blob for `chat_id`. If no row exists yet, seeds
+/// state with `"intro"` as a placeholder.
+pub(crate) fn db_save_persona(
+    conn: &Connection,
+    chat_id: i64,
+    persona_json: &str,
+    now: i64,
+) -> Result<(), BuddyError> {
+    conn.execute(
+        "INSERT INTO buddy_state (chat_id, state, persona, created_at, updated_at)
+         VALUES (?1, '\"intro\"', ?2, ?3, ?3)
+         ON CONFLICT(chat_id) DO UPDATE SET
+             persona    = excluded.persona,
+             updated_at = excluded.updated_at",
+        rusqlite::params![chat_id, persona_json, now],
+    )
+    .map_err(|e| BuddyError::Memory(e.to_string()))?;
+    Ok(())
+}

_primitives/_rust/kei-buddy/src/transition.rs

@@ -1,24 +1,30 @@
 // SPDX-License-Identifier: Apache-2.0
-//! Input struct for state-machine transitions.
+//! Output struct for `machine::handle_step`.
 //!
-//! `TransitionInput` carries the raw user message and any structured
-//! fields that an LLM extractor has already parsed from it.
-//! In the scaffold phase the `extracted_fields` value is always `null`.
+//! `TransitionInput` is removed — callers pass `(OnboardState, &str, extractor)` directly.
+//! `StepOutput` carries everything the webhook layer needs after one state step.
 
 use serde::{Deserialize, Serialize};
 
-/// Input to `OnboardState::next()`.
-///
-/// `user_text` is the verbatim Telegram message body.
-/// `extracted_fields` will hold the result of an LLM-extract call
-/// (e.g. `extractName`, `extractTone`, `extractList` from
-/// `chat-onboard-extract.ts`) once kei-cortex integration is wired.
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct TransitionInput {
-    /// Raw message text from the user, UTF-8, already trimmed.
-    pub user_text: String,
+use crate::state::OnboardState;
 
-    /// Structured fields extracted by an LLM call.
-    /// `serde_json::Value::Null` until kei-cortex integration is added.
-    pub extracted_fields: serde_json::Value,
+/// Result of a single state-machine step.
+///
+/// Mirrors the TypeScript `NextMsg` type from `chat-onboard.ts`:
+///   `{ reply, next, scratchpad, finalize? }`
+///
+/// `persona_patch` is a partial JSON object the caller must merge into
+/// the persistent persona blob. An empty object `{}` means no change.
+///
+/// `__topic_state` key inside `persona_patch` carries queue/index for
+/// the topic decomposition loop — the caller must pass it back in on
+/// the next turn by including it in the persona blob they load.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct StepOutput {
+    /// Next state to persist.
+    pub next_state: OnboardState,
+    /// Bot reply text (Markdown, Russian).
+    pub response_text: String,
+    /// Partial persona update; merge into existing persona blob.
+    pub persona_patch: serde_json::Value,
 }