# kcode-kmap-mutations 0.1.0
This library owns the atomic, immediate form of Kennedy's five writable Kmap
operations. It borrows the sole live `KwebDb` from `kcode-kweb-manager`; it
does not open persistence, queue work, decode JSON, or own application roots.
## Public API
`apply(database, request)` acquires the database's writer lane, reloads every
referenced node, validates the exact expected visible transactions of all
mutated existing nodes, and writes one signed transaction. It returns
`Outcome { transaction_id, created_node_id, affected_node_ids }`.
`Request` contains a typed `Operation`, a map from every mutated existing node
to its expected visible `TransactionId`, and backend-supplied `Provenance`.
`Operation` variants are:
- `ConnectNodes(Vec<NodeId>)`
- `ConsolidateFanout { parent, fanout, aggregator }`
- `SetFixedConnection { parent, child, slot }`
- `CreateNode { parents, owner, short_name, short_description, long_description }`
- `UpdateNode { id, owner, short_name, short_description, long_description }`
`OwnerSelection` is `Unowned`, `SelfNode`, or `Node(NodeId)` and maps directly
to Kweb ownership representation.
`Error::kind()` returns `InvalidInput`, `NotFound`, `StaleRevision`,
`Unavailable`, or `Internal`. Stale revisions are terminal for one submitted
command; unavailable errors may be retried by the durable command lane.
## Operation invariants
`ConnectNodes` places every other supplied node at the front of each node's
recent list in supplied order and retains prior distinct recent connections.
`ConsolidateFanout` removes the fanout from the parent's recent list, appends
the aggregator if absent, and appends missing fanout entries to the
aggregator's recent list.
`SetFixedConnection` uses one-based contiguous positions. A child is removed
from any old position before replacing or appending its requested position;
`None` clears an existing position.
`CreateNode` starts with its parents as recent connections and inserts the new
node at the front of each parent's recent list. `UpdateNode` changes only
owner and text, preserving connections and objects.
Every referenced canonical node must exist. Expected revisions contain
exactly the distinct existing nodes whose data the operation mutates. All
validation happens after the writer lane is acquired, so the transaction never
commits against a stale pre-lock observation.