# Public API
```rust
use std::{path::Path, sync::Arc};
use kcode_k1_txn_ordering::{K1TxnOrdering, SubsystemId};
pub struct K1Peering;
impl K1Peering {
pub fn open(
root: &Path,
ordering: Arc<K1TxnOrdering>,
) -> Result<Self, String>;
pub fn submit_txn(
&self,
subsystem: SubsystemId,
payload: &[u8],
) -> Result<(), String>;
}
```
# Identity and startup
`open` uses `root/identity.key` for the local Ed25519 identity and retains the supplied live KTO instance. Peering does not open or own the KTO root. Subsystems register directly with KTO and receive state updates only through KTO callbacks.
A missing peering root is created. The root and identity must be real directories and files rather than symbolic links. A new `identity.key` is created only when the supplied KTO has no canonical tip. It contains exactly the Ed25519 32-byte private seed followed by its corresponding 32-byte public key. Creation uses OS randomness, exclusive file creation, file synchronization, and owner-only Unix permissions. Existing key material is accepted only when it is a regular 64-byte file, its public key corresponds to its private seed, and on Unix it grants no group or other permissions.
A missing identity with nonempty canonical KTO history is rejected rather than generating a different leader identity. A malformed, mismatched, wrongly typed, symlinked, or over-permissive identity is rejected. An interrupted or failed identity installation is not repaired or replaced automatically. Key bytes are never included in errors or diagnostics.
Only one process and one live KTO instance may use the supplied KTO root, as required by KTO. Peering adds no persistent subsystem state, authorized-key registry, recovery policy, migration, or background work.
# Submission
`submit_txn` reads the current Unix timestamp in seconds and invokes KTO's local-transaction operation with the persisted public key, subsystem ID, payload, a one-shot Ed25519 signer, and successful no-op propagation.
KTO atomically selects the durable parent, constructs and signs the complete transaction, calculates its transaction ID, stores the bytes, publishes canonical order, and invokes the active target subsystem callback. Peering does not inspect or calculate the parent or transaction ID. It discards the exact committed bytes returned by KTO.
The target subsystem must already be actively registered directly with KTO. Otherwise submission fails before mutation. A successful call returns only after the target callback completes. Peering returns KTO and clock failures as strings and performs no retries. An error that identifies a transaction ID as committed records a committed transaction and must not be retried as a precommit rejection.
Peering is not a subsystem. Subsystems never apply their own submitted payload directly. They submit through peering and update their durable materialization only when KTO later invokes their canonical callback.
# Concurrency and performance
Peering has no mutex, queue, admission limit, retry, timeout, polling, worker, or async runtime. Concurrent submissions call KTO independently. KTO owns durable-tip selection, commit serialization, propagation ordering, and subsystem callback lanes.
For payload length `B`, peering-owned submission work is `O(B)` Ed25519 signing with one transaction-sized signing read and no transaction-sized peering allocation. KTO then performs its documented `O(B)` construction and persistence. Startup performs fixed work over one 64-byte key file plus OS-random generation only for a new identity. No finite wall-clock guarantee applies to entropy, storage, KTO lane wait, signing, or the subsystem callback.
Callers hold no subsystem persistence lock while submitting or waiting. Recursive submission to the same subsystem from its callback is unsupported by KTO. A blocked operation creates no additional peering-side coordination beyond KTO's documented lanes.