kcode-k1-access-kmap 0.5.0

# Access-controlled Kmap

This library exposes Kmap nodes through Access identities and authorization.

## Public API

```rust
use std::sync::Arc;

pub use kcode_k1_access::{
    AccessContext, AccessId, AccessPolicy, AccessRevision, ProfileId,
};
pub use kcode_k1_kmap::{
    ConnectionTier, MeasurementImportance, OpenMode, TxId, Weight,
};

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct ConnectionSpec {
    pub target: AccessId,
    pub tier: ConnectionTier,
}

#[derive(Clone, Debug, PartialEq)]
pub struct Connection {
    pub target: AccessId,
    pub tier: ConnectionTier,
    pub weight: Weight,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct Measurement {
    pub source: AccessId,
    pub target: AccessId,
    pub useful: bool,
    pub importance: MeasurementImportance,
}

#[derive(Clone, Debug, PartialEq)]
pub struct Node {
    pub access_id: AccessId,
    pub title: String,
    pub navigation_hint: String,
    pub narrative: String,
    pub connections: Vec<Connection>,
}

#[derive(Clone, Debug, PartialEq)]
pub struct LoadedNode {
    pub access_id: AccessId,
    pub source: Option<AccessId>,
    pub title: String,
    pub navigation_hint: String,
    pub narrative: Option<String>,
}

#[derive(Clone, Debug, PartialEq)]
pub struct OpenResult {
    pub nodes: Vec<LoadedNode>,
    pub automatic_attention_spent: f64,
}

pub struct K1AccessKmap;

impl K1AccessKmap {
    pub fn open(access: Arc<K1Access>, kmap: Arc<K1Kmap>) -> Result<Self, String>;
    pub fn create_node(
        &self,
        context: &AccessContext,
        profile_id: ProfileId,
        policy: AccessPolicy,
        title: String,
        navigation_hint: String,
        narrative: String,
        connections: Vec<ConnectionSpec>,
    ) -> Result<AccessRevision, String>;
    pub fn get_node(&self, context: &AccessContext, node: AccessId) -> Result<Node, String>;
    pub fn open_node(
        &self,
        context: &AccessContext,
        root: AccessId,
        budget: f64,
        temperature: f64,
        mode: OpenMode,
    ) -> Result<OpenResult, String>;
    pub fn update_node(
        &self,
        context: &AccessContext,
        node: AccessId,
        title: Option<String>,
        navigation_hint: Option<String>,
        narrative: Option<String>,
        connection_updates: Vec<ConnectionSpec>,
    ) -> Result<TxId, String>;
    pub fn apply_measurements(
        &self,
        context: &AccessContext,
        measurements: Vec<Measurement>,
    ) -> Result<TxId, String>;
}
```

`K1Access` and `K1Kmap` in `open` are the types owned by their respective packages.

## Semantics

All node identities crossing this API are `AccessId`s. Reads require view; content mutations require view and edit for every source, while every connection or measurement target requires view. Authorization uses the supplied context, including its authority filter, and models receive no edit path beyond the rights reported by Access.

`create_node` accepts a saved `ProfileId` from composition and passes it to Access as metadata; this wrapper does not resolve profiles. Authorization remains the concrete supplied `AccessPolicy`. The operation rejects a policy whose authority is filtered before validating all initial targets or creating the raw node. It then creates the raw node before its Access record; an unexpected Access failure after raw creation reports a possible inaccessible orphan and is not rolled back.

`get_node` omits hidden connections. `open_node` filters each raw candidate batch through Access before denied nodes can affect reads or returned edges. Hidden edges are excluded before path strength, scoring, cost, budget, or randomness in either traversal mode. For visible positional duplicates, traversal uses cumulative path strength: the root has strength 1.0, each visible edge multiplies the inherited strength, and temperature applies to the cumulative score. Visible order and positional duplicates are preserved. Each loaded node exposes the authorized visible Access identity of the raw node that directly sourced it; the root has no source. A dependency result whose loaded node or source lacks an authorized visible mapping fails as a contextual dependency-consistency error without exposing raw identities.

An unavailable, unauthorized, filtered, wrong-subsystem, or malformed supplied node is reported only as `node unavailable`. These are semantic concealment outcomes from Access checks or absent visibility results. Operational failures from the Access dependency are preserved with operation context instead of being concealed as unavailable. Mutations authorize the complete batch before raw Kmap mutation, so one denied item rejects the whole operation. Empty measurement batches retain raw Kmap behavior.

## Performance

`open` is not yet benchmarked and performs constant facade work without I/O of its own.

`create_node` is not yet benchmarked; facade-owned work scales linearly with initial connections around one batched authorization and delegated mutations.

`get_node` is not yet benchmarked; facade-owned work scales linearly with outgoing connections around one batched visibility resolution.

`open_node` is not yet benchmarked; facade-owned work scales with raw candidate positions and loaded nodes, while traversal and callback completion are delegated without a finite wall-clock bound.

`update_node` is not yet benchmarked; facade-owned work scales linearly with supplied connection updates around one batched authorization.

`apply_measurements` is not yet benchmarked; facade-owned work scales linearly with measurement positions around one batched authorization.