# Public API
```rust
use std::path::Path;
pub use kcode_k1_transaction::SubsystemId;
pub use kcode_k1_transaction_store::TxId;
pub struct OrderStore;
impl OrderStore {
pub fn create(path: &Path) -> Result<Self, String>;
pub fn open(path: &Path) -> Result<Self, String>;
pub fn entries(&self) -> &[(TxId, SubsystemId)];
pub fn index_of(&self, id: TxId) -> Option<usize>;
pub fn commit(
&mut self,
retained_len: usize,
id: TxId,
subsystem: SubsystemId,
) -> Result<(), String>;
}
```
`OrderStore` is the sole owner of one canonical order file at the exact caller-supplied path. `create` requires that path to be absent and creates an empty regular file without creating parent directories. An existing path, missing parent directory, or invalid caller path returns a definite `String`; any other file-creation failure is a fatal storage failure and aborts the process. `open` requires an existing regular file. Symlinks, directories, other file types, multiple live store instances, other processes accessing the file, external mutation, and network filesystems are unsupported.
The file is a headerless oldest-first sequence of exact 32-byte records:
| Byte range | Value |
| --- | --- |
| `0..12` | `TxId` bytes |
| `12..32` | `SubsystemId` bytes |
A valid file length is a multiple of 32. Every transaction ID must be unique and must not equal `kcode_k1_transaction::GENESIS_PARENT`. Every subsystem field must be valid UTF-8 under `SubsystemId::from_bytes`. `open` reads and validates the complete file, reconstructs the ordered entries and ID index, and returns a definite `String` error for open, read, metadata, file-type, length, duplicate-ID, genesis-ID, or subsystem-format failure. It does not modify or repair an invalid file.
`entries` borrows the complete canonical sequence in oldest-first order. `index_of` returns the zero-based position of a canonical ID. Both reflect only records that have completed the required synchronization.
`commit` requires `retained_len <= entries().len()`, a non-genesis `id`, and an `id` not already present in the current canonical sequence. Invalid arguments return a `String` without changing disk or memory. `retained_len == entries().len()` appends one record. A smaller value replaces the entire suffix beginning at `retained_len` with the new record.
Before changing the file, `commit` verifies that its actual length still equals the in-memory sequence length times 32. An append writes one record and synchronizes the file before publishing it in memory. A suffix replacement truncates to the exact retained prefix and synchronizes, writes the replacement record and synchronizes again, then replaces the in-memory suffix. Removed IDs cease to be canonical.
After argument validation, any metadata, seek, truncate, write, short-write, or synchronization failure is fatal. External file-length mutation is also fatal. The process emits exactly one concise diagnostic containing `kcode-k1-order-store`, the fixed operation, and the operating-system error, then aborts. It does not retry, reopen, repair, return an ambiguous result, or retain a poisoned handle. Callers must treat process termination during mutation as an unknown commit outcome and validate by reopening during recovery.
The durability model assumes each naturally aligned 32-byte record lies wholly within one 4,096-byte sector and that such sector writes are failure-atomic. The store has no checksum, journal, crash repair, locking, or cross-process coordination. `Drop` performs no synchronization, mutation, or recovery work.
All operations are synchronous and perform no network access. The package starts no threads and has no queue, timeout, retry, polling, or background work. Filesystem calls may block indefinitely with the local device. Callers own exclusive access for mutation. Independent immutable `entries` and `index_of` calls perform no internal synchronization.
For `n` records, `create` performs constant work and creates one file. `open` performs `O(n)` sequential read, validation, and index construction, with `O(n)` retained memory for one entry vector and one hash index. It does not read transaction payloads. `entries` is `O(1)` and allocation-free. `index_of` has expected `O(1)` work and is allocation-free. An append commit has expected `O(1)` memory work and writes exactly 32 bytes with one file synchronization. Replacing a suffix of `r` records has `O(r)` memory work, one truncation, one 32-byte write, and two file synchronizations. Commit does not allocate in proportion to the file or any transaction payload.
The reproducible large-file fixture is 1,000,000 records, all with one valid subsystem and unique IDs formed from a little-endian `u64` counter followed by four zero bytes. On the Kennedy managed Rust validation environment with at least two x86-64 vCPUs, 1 GiB available memory, and local SSD-backed container storage, `open` must reconstruct and index that 32,000,000-byte fixture in less than 5 seconds. The managed test exercises all one million records and samples both entry and index results. No wall-clock guarantee is made for caller-device persistence latency outside that fixture.