# kcode-session-log Specification
## Scope
The crate owns append-ordered role/text transcripts, pending-object sidecars,
integrity validation, incomplete-tail recovery, sealing, and exact cleanup.
The caller owns event meaning, session lifecycle, context policy, tool
semantics, database transactions, and completed-session indexing.
## Logical model
A session has one `SessionHeader` followed by ordered `SessionEvent` values.
The header contains only format version, session ID, and caller-supplied
creation-time text. An event contains only `Role` and text. Its zero-based
array position is stable identity and is not serialized inside the event.
Events are append-only, never reordered, and never removed. The durable format
version is `0.2.1`.
## Files
An active session uses:
```text
<session-id>.session-log
<session-id>-<event-position>.pending-object
```
Session IDs are one to 255 ASCII bytes consisting only of alphanumeric
characters, `-`, and `_`.
Session logs begin with fixed magic and contain framed header, event, and
sealed-footer records. Each frame stores its kind, payload length, SHA-256
payload checksum, and payload. Headers and events use JSON payloads.
A pending-object file stores fixed magic, format version, filename, media
type, declared byte length, SHA-256 byte checksum, and the original bytes.
Filename and media type must be nonempty UTF-8 text.
## Mutation and durability
One process-local lock serializes mutations for a session path. Before each
mutation, the handle reloads the durable log so multiple in-process handles do
not overwrite one another's appends.
Appending an ordinary event writes one complete frame and synchronizes the
session file before returning.
Adding a pending object:
1. reserves the next event position while holding the session lock;
2. writes and synchronizes a same-directory temporary object file;
3. atomically renames it to the final pending-object filename;
4. synchronizes the directory;
5. appends and synchronizes the referencing event.
The protocol never makes a durable event reference object bytes that were not
already synchronized.
## Opening and recovery
Opening verifies magic, frame structure, supported format, session identity,
and every complete-frame checksum. It truncates and synchronizes only an
incomplete trailing frame or payload. A complete checksum mismatch, invalid
structure, event after sealing, duplicate header, or duplicate footer is
corruption and fails opening.
After loading the transcript, opening removes recognized temporary object
files and final object files that no event references. Every referenced object
must exist and pass format, declared-length, UTF-8, and checksum validation.
Cleanup matches only exact validated filenames for the current session ID and
canonical decimal event positions.
## Sealing and deletion
Sealing verifies every referenced pending object and appends one synchronized
empty footer. It is idempotent and prevents later event appends.
Committed and abandoned deletion have identical storage mechanics. They remove
the exact session-log path and recognized sidecars, then synchronize the
directory. The caller decides which lifecycle operation is appropriate.
## Concurrency boundary
The crate coordinates its own handles within one process. Cross-process
writers and modification by software that bypasses this crate are unsupported;
the embedding application must exclude them.
## Managed-library layout
The directory is independently buildable and publishable without a parent
workspace. Root `Cargo.toml` contains the literal package name and canonical
stable version, and root `Documentation.md` is the agent-facing API reference.
All maintained files are ordinary UTF-8 text. `Cargo.lock`, build output, and
other generated state remain outside the managed source directory.