# kcode-k1-kmap-format
This crate owns Kmap node, connection, measurement, action, validation, and binary-wire invariants. It contains no persistence, callbacks, access policy, sampling, randomness, networking, or application behavior.
## Identifiers and connection state
`NodeId(pub [u8; 12])` converts losslessly to and from the canonical 12-byte K1 `TxId`. A `Node` has no identity field; its projection row owns its identity. `KmapAction::CreateNode` also has no identity because its callback transaction ID becomes the new node ID.
`ConnectionTier` is either `Navigation` or `Automated`. `ConnectionSpec { target, tier }` describes an upsert. `Connection { target, tier, weight }` is directed state inside its source node. Targets must be unique, and at most `MAX_NAVIGATION_CONNECTIONS` (12) connections may be `Navigation`; `Automated` connections and all text fields have no arbitrary cardinality or length cap.
`Weight { value, mass }` is public durable state. `Weight::new` accepts only finite values in `[0, 1]` and finite positive masses. `Weight::initial()` is exactly `{ value: 1.0, mass: 3.0 }`. `Weight::update(value, mass)` validates both the stored and supplied values, ages stored mass by `2^(-mass / EWA_HALF_LIFE_MASS)` with half-life mass 30, incorporates the supplied sample, and returns `None` only when the updated value is strictly below `PRUNE_EPSILON` (0.1).
## Nodes and updates
`Node::new` validates complete connection state. `Node::from_specs` creates initial-weight connections in supplied order after validating target uniqueness and the Navigation limit. `Node::validate` checks unique targets, every stored weight, and the Navigation limit.
`Node::apply_connection_updates(&[ConnectionSpec])` is atomic. Duplicate update targets are rejected before mutation. An update for an existing target changes its tier while preserving its weight and position. An update for a missing target appends a new initial-weight connection, preserving supplied order among additions. Empty updates are valid. There is no connection-removal operation.
`MeasurementImportance` is `Critical` or `NonCritical`. `ConnectionMeasurement { source, target, useful, importance }` is constructed infallibly by `ConnectionMeasurement::new`. Measurement callers cannot choose numeric values or masses: useful maps to value 1, not useful maps to value 0, Critical maps to mass 3, and NonCritical maps to mass 1.
`Node::apply_measurement(target, useful, importance)` updates a present target with those mappings. It returns `MeasurementOutcome::Updated`, removes a connection and returns `Pruned` when its updated value is below 0.1, or returns `Absent` without mutation when the target is missing.
## Actions and wire format
`KmapAction` contains `CreateNode`, `UpdateNode`, and ordered `ApplyMeasurements` variants. `KmapAction::create_node`, `update_node`, and `apply_measurements` construct and validate their action-local invariants. `UpdateNode` carries `connection_updates: Vec<ConnectionSpec>` with unique targets. Projection code applies node updates and remains responsible for validating resulting complete node state.
`Node::encode` and `KmapAction::encode` validate and emit deterministic Postcard payloads prefixed by `FORMAT_VERSION`, which is 2. Their decoders accept only version 2 and reject empty, unsupported, malformed, trailing, and invariant-invalid values. Consumers must use these methods rather than serializing public fields directly as a wire substitute.
Validation and wire failures return `KmapError(String)` through the public `Result<T>` alias. Operations are synchronous, perform no network request, retry, or timeout, and take work and allocation linear in the encoded value or supplied collection.