# Public API
```rust
use std::sync::Arc;
use kcode_k1_peering::K1Peering;
use kcode_k1_txn_ordering::K1TxnOrdering;
pub use kcode_k1_transaction_id::TxId;
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct Object {
pub filename: String,
pub file_type: String,
pub description: String,
pub data: Vec<u8>,
}
pub struct K1Objects;
impl K1Objects {
pub fn open(ordering: Arc<K1TxnOrdering>, peering: Arc<K1Peering>) -> Result<Self, String>;
pub fn save(
&self,
filename: &str,
file_type: &str,
description: &str,
data: &[u8],
) -> Result<TxId, String>;
pub fn load(&self, id: TxId) -> Result<Option<Object>, String>;
}
```
# Lifecycle
`open` registers subsystem ID `k1-objects-subsystem` with ordering at `REGISTER_AT_TIP`. It receives no historical callbacks and owns no materialized state. Peering must use the same live ordering instance. Canonical transaction bytes are the only object persistence, so historical objects remain loadable by transaction ID. A reorganization may take the registration out of commission; reopening at the current tip restores submission.
Performance: Not yet benchmarked; `open` performs bounded in-memory registration work without a historical scan or payload read.
# Objects
`save` accepts empty or arbitrary UTF-8 metadata and opaque binary data without validating filename, file type, or description semantics. Every success creates a new canonical transaction; equal inputs are not deduplicated. It returns peering's exact committed transaction ID after canonical callback completion. An error identifying that ID as committed is not retry permission.
Performance: Not yet benchmarked; for total metadata bytes `M` and data bytes `B`, `save` performs `O(M + B)` work and allocates one `25 + M + B` byte payload before synchronous signing, persistence, and callback completion, with no timeout or retry.
`load` queries the current canonical chain. An unknown or noncanonical ID, or a canonical transaction for another subsystem, returns `Ok(None)`. A valid Objects transaction returns a complete owned value. Unsupported payload versions, malformed framing, out-of-bounds lengths, and non-UTF-8 metadata return `Err`; file type and data remain opaque.
Performance: Not yet benchmarked; for complete transaction bytes `T`, metadata bytes `M`, and data bytes `B`, `load` performs `O(T + M + B)` retrieval, validation, and copying, with peak memory for the retrieved transaction and returned object and no timeout or retry.
# Payload format
Version 1 payloads contain byte `1`, then filename, file-type, and description UTF-8 byte lengths as three little-endian `u64` values, then those fields in order, followed by all remaining bytes as data. Inputs are accepted when each length fits `u64`, the complete payload length fits `usize`, and allocation succeeds; there is no additional size cap.