# API
`kcode-session-history` is Kennedy's private durable session library. It owns
the active `.session-log` files supplied by `kcode-session-log`, lifecycle and
command control journals, staged objects, reconstructed Chatend state, and the
append-only completed-session receipt list.
The crate is not an HTTP component. It has no Axum types, routes, status codes,
multipart parsing, Kweb transaction API, or KennedyServer dependency.
## Dependency and opening
Version 0.1.0 is published to crates.io for use by Kennedy components:
```toml
[dependencies]
kcode-session-history = "0.1.0"
```
Open one long-lived, cheaply cloneable `SessionHistory` for a persistence
root:
```rust,no_run
use kcode_session_history::{Config, SessionHistory};
let history = SessionHistory::open(Config {
directory: "data/sessions/in-progress".into(),
completed_list: "data/session-history.txt".into(),
})?;
# Ok::<(), anyhow::Error>(())
```
`SessionHistory::open` creates private directories and the completed-list file
when absent, verifies and compacts active control journals, and preserves the
authoritative session logs and pending objects. The library owns the files it
derives beneath `Config::directory` and the exact file at
`Config::completed_list`.
## Public store types
```rust
pub struct Config {
pub directory: std::path::PathBuf,
pub completed_list: std::path::PathBuf,
}
pub struct NewSession {
pub kind: chatend::SessionKind,
pub created_at: String,
pub effective_context_tokens: u64,
pub channel: serde_json::Value,
}
pub struct RegisterSession {
pub id: String,
pub started_at: String,
pub state: serde_json::Value,
}
pub struct StartSession {
pub idempotency_id: String,
pub started_at: String,
pub session_type: String,
pub duration_minutes: Option<f64>,
pub custom_prompt: Option<String>,
}
pub struct SessionRecord {
pub id: String,
pub phase: String,
pub started_at: String,
pub updated_at: String,
pub state: serde_json::Value,
pub provenance_id: Option<String>,
pub version: i64,
pub last_user_message_at: Option<String>,
pub ended_at: Option<String>,
pub ingress_failure_count: i64,
pub ingress_failures: serde_json::Value,
pub ingress_next_attempt_at: Option<String>,
pub summary: bool,
}
pub struct Created<T> {
pub value: T,
pub created: bool,
}
```
`created` distinguishes a new idempotent operation from a replay that returned
the existing value. Active record phases are `active`, `ingress_pending`,
`ingress_in_progress`, and `ingress_failed`; completed-list records materialize
as `complete`. `version` is the optimistic-concurrency value required by
checkpoint and transition inputs.
## Session creation and discovery
```rust
impl SessionHistory {
pub fn open(config: Config) -> anyhow::Result<SessionHistory>;
pub fn health(&self) -> Result<(), Error>;
pub fn create_session(&self, input: NewSession)
-> anyhow::Result<Session>;
pub fn open_session(&self, metadata: chatend::SessionMetadata)
-> anyhow::Result<Session>;
pub async fn register(&self, input: RegisterSession)
-> Result<SessionRecord, Error>;
pub async fn start(&self, input: StartSession)
-> Result<Created<SessionRecord>, Error>;
pub async fn list(&self) -> Result<Vec<SessionRecord>, Error>;
pub async fn get(&self, id: &str) -> Result<SessionRecord, Error>;
}
```
There are two intentional creation flows:
- `create_session` assigns a UUID and returns a mutable `Session` for a
Kennedy execution. After the caller has built its initial application state,
`register` attaches the lifecycle journal to that same durable log.
- `start` is the idempotent lifecycle-first path used for backend-managed work.
It assigns the session ID and creates the transcript and control journal
together.
`open_session` reconstructs the mutable Chatend projection from an existing
session log. The supplied `SessionMetadata` identity and creation time must
match the durable header. No public operation accepts or returns an individual
session-log path.
`list` returns active sessions plus immutable completion receipts, newest
updated first. Active entries are summary projections. `get` returns the full
active projection or a completed receipt selected by its canonical archive
object ID.
## Commands and staged objects
```rust
pub struct NewCommand {
pub idempotency_id: String,
pub kind: String,
pub payload: serde_json::Value,
}
pub struct SessionCommand {
pub id: String,
pub conversation_id: String,
pub sequence: i64,
pub kind: String,
pub payload: serde_json::Value,
pub status: String,
pub cancel_requested: bool,
pub outcome: Option<serde_json::Value>,
pub created_at: String,
pub processing_started_at: Option<String>,
pub completed_at: Option<String>,
pub idempotency_id: String,
}
pub struct CommandOutcome {
pub outcome: serde_json::Value,
}
pub struct NewObject {
pub file_name: Option<String>,
pub media_type: String,
pub bytes: Vec<u8>,
}
pub struct StoredObject {
pub file_name: String,
pub media_type: String,
pub bytes: Vec<u8>,
}
impl SessionHistory {
pub async fn enqueue(
&self,
id: &str,
input: NewCommand,
) -> Result<Created<SessionCommand>, Error>;
pub async fn command_heads(&self)
-> Result<Vec<SessionCommand>, Error>;
pub async fn claim_command(&self, id: &str)
-> Result<SessionCommand, Error>;
pub async fn complete_command(
&self,
id: &str,
outcome: CommandOutcome,
) -> Result<SessionCommand, Error>;
pub async fn stage_object(
&self,
id: &str,
object: NewObject,
) -> Result<String, Error>;
pub fn object(
&self,
id: &str,
pending_id: &str,
) -> Result<StoredObject, Error>;
}
```
Commands are ordered per active session. Only the earliest unfinished command
is claimable. Enqueue is idempotent by `idempotency_id`; command states are
`pending`, `processing`, and `complete`.
`stage_object` takes ownership of complete bytes and returns the durable
event-derived ID `pending:N`. Object staging is rejected while a command is
unfinished so independent handles cannot race allocation. `object` verifies
the pending object and returns a safe filename, usable media type, and owned
bytes.
## Lifecycle and completion
```rust
pub struct Checkpoint {
pub expected_version: i64,
pub state: serde_json::Value,
pub user_activity: bool,
}
pub struct ExpectedVersion {
pub expected_version: i64,
}
pub struct StartIngress {
pub expected_version: i64,
pub provenance_id: String,
}
pub struct IngressFailure {
pub expected_version: i64,
pub stage: String,
pub code: Option<String>,
pub message: String,
pub rounds_used: Option<u64>,
pub context_tokens: Option<u64>,
pub context_window_tokens: Option<u64>,
}
pub struct RetryIngress {
pub expected_version: i64,
pub state: serde_json::Value,
}
impl SessionHistory {
pub async fn checkpoint(
&self,
id: &str,
input: Checkpoint,
) -> Result<SessionRecord, Error>;
pub async fn stop(&self, id: &str)
-> Result<SessionRecord, Error>;
pub async fn request_ingress(
&self,
id: &str,
input: Checkpoint,
) -> Result<SessionRecord, Error>;
pub async fn start_ingress(
&self,
id: &str,
input: StartIngress,
) -> Result<SessionRecord, Error>;
pub async fn complete_ingress(
&self,
id: &str,
input: ExpectedVersion,
) -> Result<SessionRecord, Error>;
pub async fn fail_ingress(
&self,
id: &str,
input: IngressFailure,
) -> Result<SessionRecord, Error>;
pub async fn retry_ingress(
&self,
id: &str,
input: RetryIngress,
) -> Result<SessionRecord, Error>;
pub async fn release_interrupted_ingress(&self)
-> Result<Vec<String>, Error>;
pub async fn complete(
&self,
id: &str,
input: Checkpoint,
) -> Result<SessionRecord, Error>;
}
```
All mutation inputs carrying `expected_version` use optimistic concurrency and
return `Conflict` when stale. `checkpoint` retains a new application snapshot
without changing phase. `stop` and `request_ingress` move active work to
`ingress_pending`; `start_ingress` claims it and records provenance.
`fail_ingress` applies the fixed retry policy. Retryable failures below the
five-attempt budget return to `ingress_pending` with a short delay. The fifth
failure, or a non-retryable failure, enters `ingress_failed`. Only the five
latest concise failures are embedded in the lifecycle record.
`retry_ingress` manually grants a fresh attempt budget while retaining the
failure count. `release_interrupted_ingress` requeues claims left in progress
by process interruption.
`complete` commits a final state directly. `complete_ingress` commits the
current state after ingress. These lifecycle operations do not themselves
write Kweb data or remove local session data.
Completion receipts are recorded separately after the embedding application
has committed Kweb:
```rust
pub struct RecordCompletion {
pub session_object_id: String,
pub commit_receipt: Option<CompletionReceipt>,
pub session_id: Option<String>,
pub session_type: Option<String>,
pub created_at: Option<String>,
}
pub struct CompletionReceipt {
pub transaction_id: Option<String>,
pub session_object_id: String,
pub session_id: Option<String>,
pub session_type: Option<String>,
pub created_at: Option<String>,
pub committed_at: Option<String>,
pub node_ids: std::collections::BTreeMap<String, String>,
pub object_ids: std::collections::BTreeMap<String, String>,
}
impl SessionHistory {
pub async fn record_completion(
&self,
input: RecordCompletion,
) -> Result<(), Error>;
}
```
`record_completion` synchronizes an idempotent JSON-lines receipt to the
completed list. When `session_id` is supplied, success then removes the exact
committed session log, its pending objects, and its control journal. Historical
completed-list lines containing only an object ID remain readable.
## Mutable session and Chatend
`Session` is an opaque handle to one ordered session history. Construct it only
through `SessionHistory::create_session` or
`SessionHistory::open_session`. It exposes durable mutations without exposing
`kcode-session-log` or a storage path.
```rust
impl Session {
pub fn id(&self) -> &str;
pub fn state(&self) -> &chatend::Chatend;
pub fn objects(
&self,
) -> &std::collections::BTreeMap<
chatend::PendingId,
chatend::ObjectLocation,
>;
pub fn archive_bytes(&self) -> anyhow::Result<Vec<u8>>;
pub fn is_sealed(&self) -> bool;
pub fn seal(&mut self) -> anyhow::Result<()>;
pub fn repair_unfinished_tools(
&mut self,
recorded_at: impl Into<String>,
) -> anyhow::Result<Vec<chatend::EventId>>;
pub fn mark_completed(&mut self, session_object_id: String);
pub fn configure_context(
&mut self,
kind: chatend::SessionKind,
effective_context_tokens: u64,
);
pub fn create_box(
&mut self,
recorded_at: impl Into<String>,
name: impl Into<String>,
owner: chatend::BoxOwner,
content: chatend::BoxContent,
) -> anyhow::Result<chatend::BoxId>;
pub fn update_box(
&mut self,
recorded_at: impl Into<String>,
box_id: chatend::BoxId,
content: chatend::BoxContent,
) -> anyhow::Result<Option<chatend::EventId>>;
pub fn dehydrate_box(
&mut self,
recorded_at: impl Into<String>,
box_id: chatend::BoxId,
) -> anyhow::Result<chatend::EventId>;
pub fn summarize_box(
&mut self,
recorded_at: impl Into<String>,
box_id: chatend::BoxId,
text: impl Into<String>,
) -> anyhow::Result<chatend::EventId>;
pub fn rehydrate_box(
&mut self,
recorded_at: impl Into<String>,
box_id: chatend::BoxId,
) -> anyhow::Result<chatend::EventId>;
pub fn retire_box(
&mut self,
recorded_at: impl Into<String>,
box_id: chatend::BoxId,
) -> anyhow::Result<chatend::EventId>;
pub fn allocate_pending_node(
&mut self,
recorded_at: impl Into<String>,
) -> anyhow::Result<chatend::PendingId>;
pub fn stage_object(
&mut self,
recorded_at: impl Into<String>,
media_type: impl Into<String>,
file_name: Option<String>,
transport: serde_json::Value,
bytes: &[u8],
) -> anyhow::Result<chatend::PendingId>;
pub fn read_object(
&mut self,
id: &chatend::PendingId,
) -> anyhow::Result<Vec<u8>>;
pub fn record(
&mut self,
recorded_at: impl Into<String>,
kind: chatend::EventKind,
) -> anyhow::Result<chatend::EventId>;
pub fn commit_events(
&mut self,
recorded_at: impl Into<String>,
events: Vec<chatend::Event>,
) -> anyhow::Result<()>;
pub fn apply_tool_slots(
&mut self,
recorded_at: impl Into<String>,
tool_instance: impl Into<String>,
slots: Vec<chatend::ToolSlotInput>,
) -> anyhow::Result<Vec<chatend::EventId>>;
pub fn apply_tool_slots_with_layout(
&mut self,
recorded_at: impl Into<String>,
tool_instance: impl Into<String>,
slots: Vec<chatend::ToolSlotInput>,
layout_slots: &[String],
) -> anyhow::Result<Vec<chatend::EventId>>;
pub fn apply_box_representations(
&mut self,
recorded_at: impl Into<String>,
desired: &std::collections::BTreeMap<
chatend::BoxId,
chatend::BoxRepresentation,
>,
) -> anyhow::Result<Vec<chatend::EventId>>;
}
```
Every event-producing mutation and object-staging operation appends and
synchronizes its durable representation before updating the in-memory
projection. `seal` is idempotent and rejects unfinished tool invocations.
`repair_unfinished_tools` writes explicit recovery completions before a
recovered session is sealed.
The `chatend` module contains the provider-independent logical model:
- identity types `EventId`, `BoxId`, and validated `PendingId`;
- `SessionKind`, `SessionMetadata`, `BoxOwner`, `BoxContent`, `BoxState`,
`Representation`, and `BoxRepresentation`;
- `EventKind`, `Event`, and `Transition`;
- pending-object metadata and location types;
- `ToolSlotInput`, `ToolSlot`, and `ToolState`; and
- `Chatend`, `ContextProjection`, and `ProjectionItem`.
Its small value helpers are:
```rust
impl chatend::PendingId {
pub fn from_event(id: chatend::EventId) -> Self;
pub fn parse(value: impl Into<String>) -> anyhow::Result<Self>;
pub fn number(&self) -> u64;
}
impl chatend::BoxContent {
pub fn text(value: impl Into<String>) -> Self;
}
impl chatend::BoxState {
pub fn stale(&self) -> bool;
}
```
`EventKind` represents configuration, box creation/update/representation,
pending resource allocation, tool invocation/completion/layout, inference
submission and provider receipts, capacity failures, source termination,
history-ingress inspection, Kweb planning/commit, completion, and arbitrary
labeled notes. It serializes as a tagged snake-case enum; the concrete Rust
variants in `chatend::EventKind` are the authoritative schema.
`Chatend` exposes event/box lookup, active-box iteration, fixed context-limit
calculations, current projection, and nonmutating projection previews:
```rust
impl chatend::Chatend {
pub fn event(&self, id: chatend::EventId)
-> Option<&chatend::Event>;
pub fn box_state(&self, id: chatend::BoxId)
-> Option<&chatend::BoxState>;
pub fn active_boxes(&self)
-> impl Iterator<Item = &chatend::BoxState>;
pub fn live_context_limit(&self) -> u64;
pub fn forced_ingress_context_limit(&self) -> u64;
pub fn ingress_initial_context_limit(&self) -> u64;
pub fn ingress_context_limit(&self) -> u64;
pub fn active_context_limit(&self) -> u64;
pub fn projection_with_new_boxes(
&self,
boxes: &[(String, chatend::BoxOwner, chatend::BoxContent)],
) -> anyhow::Result<chatend::ContextProjection>;
pub fn projection_with_new_boxes_and_updates(
&self,
boxes: &[(String, chatend::BoxOwner, chatend::BoxContent)],
updates: &std::collections::BTreeMap<
chatend::BoxId,
chatend::BoxContent,
>,
) -> anyhow::Result<chatend::ContextProjection>;
pub fn projection_with_box_representations(
&self,
desired: &std::collections::BTreeMap<
chatend::BoxId,
chatend::BoxRepresentation,
>,
) -> anyhow::Result<chatend::ContextProjection>;
pub fn projection(&self) -> chatend::ContextProjection;
}
impl chatend::ContextProjection {
pub fn render(&self) -> String;
}
pub fn estimate_tokens(text: &str) -> u64;
```
The current format constant is `chatend::FORMAT_VERSION`. Objects are bounded
by `chatend::MAX_OBJECT_BYTES` per object and in aggregate per session.
Token estimation uses `chatend::ESTIMATED_CHARACTERS_PER_TOKEN`.
## Errors, concurrency, and recovery
Lifecycle methods return:
```rust
pub enum ErrorKind {
InvalidInput,
NotFound,
Conflict,
Storage,
}
pub struct Error {
pub kind: ErrorKind,
pub message: String,
}
impl ErrorKind {
pub fn code(self) -> &'static str;
}
```
`ErrorKind::code` returns `invalid_request`, `not_found`, `state_conflict`, or
`internal_error`. Storage diagnostics are logged with `tracing`; the public
storage message is intentionally generic. `Session` and opening operations use
`anyhow::Error` for internal integration failures.
Mutations through handles opened in one process are serialized per session;
completed-list changes use a catalog lock. The package does not coordinate
independent processes writing the same persistence root.
Checksummed complete control records are authoritative. Opening repairs only an
incomplete trailing record, rejects other corruption, compacts superseded
lifecycle and command records, and replays the `.session-log` to reconstruct
Chatend. No presentation snapshot is required. See `Specification.md` for the
full persistence, retry, and cleanup contract.