# Public API
```rust
use std::{path::Path, sync::Arc};
pub use kcode_k1_canonical_chain::SubmitError;
pub use kcode_k1_transaction_id::TxId;
pub use kcode_k1_transaction::{GENESIS_PARENT, REGISTER_AT_TIP, SubsystemId};
pub trait Subsystem: Send + Sync + 'static {
fn submit_txn(&self, id: TxId, payload: &[u8]) -> Result<(), String>;
fn reorg(&self) -> Result<(), String>;
}
pub struct K1TxnOrdering;
impl K1TxnOrdering {
pub fn open(root: &Path) -> Result<Self, String>;
pub fn register_subsystem(
&self,
subsystem: SubsystemId,
after: Option<TxId>,
handler: Arc<dyn Subsystem>,
) -> Result<(), String>;
pub fn submit_txn(&self, transaction: &[u8]) -> Result<(), SubmitError>;
pub fn submit_local_txn<F, Q>(
&self,
timestamp: u64,
creator: [u8; 32],
subsystem: SubsystemId,
payload: &[u8],
signer: F,
queue_propagation: Q,
) -> Result<(TxId, Vec<u8>), String>
where
F: FnOnce(&[u8]) -> Result<[u8; 64], String>,
Q: FnOnce(&[u8]) -> Result<(), String>;
pub fn contains(&self, id: TxId) -> bool;
pub fn tip(&self) -> Option<TxId>;
pub fn between_txids(&self, older: TxId, newer: TxId) -> Result<Vec<TxId>, String>;
pub fn get_txn(&self, id: TxId) -> Result<Option<Vec<u8>>, String>;
}
```
# Storage and ordering
`open` initializes an absent or empty real root and opens a complete existing root. It rejects mixed, wrongly typed, symlinked, malformed, or externally mutated storage. Complete transaction bytes become durable before their order record. Storage ambiguity or corruption is fatal rather than returned as an ordinary error. The caller supplies one live instance and process over supported local storage.
Performance: On the managed one-million-record fixture, `open` is `O(N)` time and memory without payload reads and completes within five seconds; completion over 100 milliseconds emits a secret-free warning.
`submit_txn` accepts complete peer bytes after caller validation of signature, authority, timestamp, ingress policy, and parent-first order. Unknown or noncanonical parents return `SubmitError::MissingParent` without mutation. Exact canonical duplicates succeed without delivery. Siblings rank by lower complete creator key, then timestamp, then complete SHA-256 digest; a winning sibling replaces the canonical suffix, while a loser is not stored. `GENESIS_PARENT` is the first-transaction parent sentinel, and `REGISTER_AT_TIP` cannot be a transaction parent. Callback failure or panic is returned as `SubmitError::Other` identifying the committed `TxId`; it faults only that registration and does not undo commitment.
Performance: Not yet benchmarked; for transaction length `B` and replaced suffix length `R`, `submit_txn` performs `O(B + R)` work plus local persistence and synchronous applicable callbacks, with no timeout or retry.
`submit_local_txn` requires an active target registration. It signs once, durably commits bytes and ordering, queues propagation with the complete committed bytes, and then delivers to the target. Signer failure or panic precedes mutation. Queue or callback failure after commitment returns an error identifying the committed `TxId` and must not be retried as a precommit rejection. On success, `id == TxId::for_transaction(&bytes)`. A later winning peer fork may reorganize the transaction.
Performance: Not yet benchmarked; for payload length `B`, `submit_local_txn` performs `O(B)` local work plus persistence, signer, propagation, lane wait, and callback time, with one signer call, one propagation call, and no timeout or retry.
# Subsystems
`register_subsystem` interprets `after` as follows: `None` or `Some(GENESIS_PARENT)` replays matching canonical transactions from genesis; `Some(REGISTER_AT_TIP)` activates at the current tip without history; any other value must identify a canonical transaction for that subsystem and replays strictly after it. Replay is oldest first and transitions without gaps or duplicates to live delivery. Re-registration replaces only an out-of-commission or faulted registration with no outstanding work.
Each registration receives same-subsystem callbacks in canonical commit order. Callback failure or panic faults only that registration. A winning reorganization invokes `reorg` for each active registration whose delivered state was removed and takes it out of commission. Callbacks are synchronous and unretried. A blocked callback does not prevent unrelated subsystem work or queries; recursive submission to the same subsystem is unsupported.
Only canonical callbacks for a subsystem may update that subsystem's durable materialization, and replay of that subsystem alone must reproduce it. A subsystem with no materialized state may register at `REGISTER_AT_TIP` and retrieve historical canonical transactions by ID.
Performance: Not yet benchmarked; `register_subsystem` scans `O(N)` canonical records and reads matching transactions for genesis or real-cursor replay, while tip registration performs bounded in-memory work without history or payload reads, and callback latency has no finite bound.
# Queries
`contains` excludes both reserved sentinels.
Performance: Not yet benchmarked; `contains` performs `O(1)` in-memory work with no I/O.
`tip` returns the newest canonical transaction ID.
Performance: Not yet benchmarked; `tip` performs `O(1)` in-memory work with no I/O.
`between_txids` uses exclusive canonical boundaries and returns IDs oldest first. `older` may be `GENESIS_PARENT`; other boundaries must be canonical. Equal valid boundaries return an empty vector, while unknown or reversed boundaries are errors. Results contain at most 128 IDs selected by the canonical chain's documented even-sampling formula.
Performance: Not yet benchmarked; `between_txids` performs bounded in-memory work and returns at most 128 IDs with no I/O.
`get_txn` returns `None` for a noncanonical ID and aborts if canonical bytes are missing or corrupt.
Performance: Not yet benchmarked; for transaction length `B`, `get_txn` performs `O(B)` work and one local payload read with no timeout or retry.