# Public API
`K1Kmap` is the synchronous public facade.
```rust
pub struct K1Kmap;
impl K1Kmap {
pub fn open(
root: &std::path::Path,
ordering: std::sync::Arc<kcode_k1_txn_ordering::K1TxnOrdering>,
peering: std::sync::Arc<kcode_k1_peering::K1Peering>,
) -> Result<Self, String>;
pub fn create_node(
&self,
title: impl Into<String>,
navigation_hint: impl Into<String>,
narrative: impl Into<String>,
connections: Vec<ConnectionSpec>,
) -> Result<TxId, String>;
pub fn update_node(
&self,
node_id: NodeId,
title: Option<String>,
navigation_hint: Option<String>,
narrative: Option<String>,
connection_updates: Vec<ConnectionSpec>,
) -> Result<TxId, String>;
pub fn apply_measurements(
&self,
measurements: Vec<ConnectionMeasurement>,
) -> Result<TxId, String>;
pub fn get_node(&self, node_id: NodeId) -> Result<Option<Node>, String>;
pub fn open_node(
&self,
node_id: NodeId,
budget: f64,
temperature: f64,
mode: OpenMode,
candidate_filter: impl FnMut(&[NodeId]) -> Result<Vec<NodeId>, String>,
) -> Result<OpenResult, String>;
}
```
The facade reexports these loader declarations:
```rust
pub const PREVIEW_COST: f64 = 0.3;
pub const NARRATIVE_COST: f64 = 1.0;
pub enum OpenMode { Full, NavigationOnly }
pub struct LoadedNode {
pub node_id: NodeId,
pub title: String,
pub navigation_hint: String,
pub narrative: Option<String>,
}
pub struct OpenResult {
pub nodes: Vec<LoadedNode>,
pub automatic_attention_spent: f64,
}
```
`OpenMode` implements `Clone + Copy + Debug + Eq + PartialEq`; `LoadedNode` and `OpenResult` implement `Clone + Debug + PartialEq`.
The facade reexports these format declarations:
```rust
pub struct NodeId(pub [u8; 12]);
pub enum ConnectionTier { Navigation, Automated }
pub struct Weight { pub value: f64, pub mass: f64 }
pub struct Connection {
pub target: NodeId,
pub tier: ConnectionTier,
pub weight: Weight,
}
pub struct ConnectionSpec { pub target: NodeId, pub tier: ConnectionTier }
pub enum MeasurementImportance { Critical, NonCritical }
pub struct ConnectionMeasurement {
pub source: NodeId,
pub target: NodeId,
pub useful: bool,
pub importance: MeasurementImportance,
}
pub enum MeasurementOutcome { Updated, Pruned, Absent }
pub struct Node {
pub title: String,
pub navigation_hint: String,
pub narrative: String,
pub connections: Vec<Connection>,
}
pub enum KmapAction {
CreateNode {
title: String,
navigation_hint: String,
narrative: String,
connections: Vec<ConnectionSpec>,
},
UpdateNode {
node_id: NodeId,
title: Option<String>,
navigation_hint: Option<String>,
narrative: Option<String>,
connection_updates: Vec<ConnectionSpec>,
},
ApplyMeasurements { measurements: Vec<ConnectionMeasurement> },
}
pub struct KmapError(pub String);
pub type Result<T> = std::result::Result<T, KmapError>;
```
`Weight` exposes `new(value, mass)`, `initial()`, and `update(value, mass)`. `Connection` exposes `new(target, tier)`. `ConnectionMeasurement::new(source, target, useful, importance)` is infallible. `Node` exposes `new`, `from_specs`, `validate`, `apply_connection_updates`, `apply_measurement`, `encode`, and `decode`. `KmapAction` exposes `create_node`, `update_node`, `apply_measurements`, `validate`, `encode`, and `decode`. Their argument and result types follow the fields above; node/action validation and encoding methods return the reexported format `Result`.
`NodeId` converts losslessly to and from the reexported 12-byte `TxId`. `NodeId` implements `Clone + Copy + Debug + Deserialize + Eq + Hash + PartialEq + Serialize`. Connection and measurement enums/specifications implement `Clone + Copy + Debug + Deserialize + Eq + PartialEq + Serialize`; `Weight`, `Connection`, `Node`, and `KmapAction` implement their source types' public `Clone + Debug + Deserialize + PartialEq + Serialize` traits. `MeasurementOutcome` implements `Clone + Copy + Debug + Eq + PartialEq`. `KmapError` implements `Clone + Debug + Display + Error + Eq + PartialEq`.
## Semantics
Each mutation submits one encoded action once through Peering. Only ordered callbacks alter the derived projection. Applied, unchanged, and semantically rejected callbacks advance its checkpoint; malformed callbacks and infrastructure failures fault the instance. Reorganization faults the instance and clears the projection. A fresh open is the recovery path.
Connection targets are unique and at most 12 may be `Navigation`. `update_node` atomically changes supplied text and upserts each connection target: existing targets are retiered without changing weight or position, while missing targets are appended with initial weight. There is no explicit connection-removal operation.
Measurements contain only semantic feedback. `useful` maps to numeric value 1 or 0; `Critical` maps to mass 3 and `NonCritical` to mass 1. Measurements apply in listed order. Missing sources and targets are no-ops. Learned weights use evidence-mass exponential averaging and a connection is pruned only when its updated value is below 0.1.
The caller authorizes the traversal root and supplies source-ordered batches of unresolved targets. The filter returns the unique allowed subset; omissions deny, malformed results reject, and callback errors retain their complete message. Decisions are cached for the call. Denied targets are removed before reads, costs, scoring, and RNG.
Budget and temperature must be finite and nonnegative. `Full` returns the root narrative, provides accessible root Navigation previews free, then uses two-hit preview/narrative loading. `NavigationOnly` returns no narratives and atomically loads a selected node with its accessible unseen Navigation children; its first unaffordable selected bundle stops traversal without resampling. Duplicate frontier paths remain weighted tickets in both modes and carry cumulative path strength: the root starts at 1.0, each edge multiplies inherited strength, and temperature applies to that cumulative score.
Operations are synchronous and have no finite wall-clock bound because callbacks, storage, entropy, and caller-supplied candidate filters may block.