# kcode Commit Session Specification
## Purpose and boundary
The library turns one fully prepared, sealed session into permanent Kweb state.
It is deliberately not a session manager: it does not own active histories,
lifecycle transitions, archives, HTTP, file-envelope formats, async runtimes,
or writer scheduling.
## Commit semantics
One successful call creates all supplied attachment objects, creates the
session archive object, reserves every pending node ID, resolves circular
pending-node references, creates nodes, and updates canonical nodes in one
Kweb transaction. Textual `pending:N` object tokens are replaced in archive
and node text only at identifier boundaries. Binary archives are preserved.
Every explicit pending reference must be canonical and resolvable. Permanent
references use `kcode-kweb-db` identifier types or canonical strings parsed
into those types.
## Idempotency and recovery
The receipt database owns `kmap_session_commit_receipts`. New rows carry a
versioned canonical SHA-256 request digest. Repeating an identical request
returns the stored receipt; changing input under the same key is a conflict.
Before Kweb finalization, a prepared receipt records every randomly allocated
object and node ID. If finalization becomes visible but the process stops
before marking the receipt complete, a replay detects the archive object and
promotes the prepared receipt. The recovered receipt has no transaction ID,
matching Kennedy's historical recovery behavior. If Kweb did not make the
transaction visible, the incomplete row is discarded and the request retries.
Existing version-1 Kennedy rows are migrated in place. Their digest was
derived from private application structs that the library intentionally does
not reproduce, so their unique session key remains authoritative.
The receipt store and Kweb are distinct durability domains. The prepared
receipt protocol provides restart recovery rather than pretending they form a
cross-database transaction.
## Concurrency
`KwebDb` serializes its own mutation transaction. The application must
serialize calls that share a receipt database with any other writers to that
database. Kennedy satisfies this with its global Kweb writer lane.