# API
`kcode-server-object-envelopes` encodes and decodes the application payloads
that KennedyServer stores as opaque Kweb objects. It does not open or mutate a
Kweb database.
```rust
use kcode_server_object_envelopes::{
StoredArtifact, StoredProvenance, decode_file, decode_provenance,
encode_file, encode_provenance, sanitize_file_name,
};
```
- `encode_file` preserves exact content bytes and writes a safe, bounded
filename, media type, and optional transport kind in the `KFILE001` payload
format. Unsafe metadata is normalized rather than retained verbatim.
- `decode_file` returns `StoredFile`. Non-marker historical raw object payloads
remain readable without rewriting and receive a conservative inferred media
type and filename. Payloads beginning with the reserved visible `KFILE`
namespace must contain a complete supported envelope; unknown or truncated
markers are rejected.
- `sanitize_file_name` treats both `/` and `\` as separators on every platform,
returns a basename of at most 255 UTF-8 bytes, sanitizes the supplied fallback
by the same policy, treats `.` and `..` as unusable path segments, and uses
`object.bin` if neither value is usable.
- `encode_provenance` and `decode_provenance` losslessly round-trip the fields
of `StoredProvenance` and its ordered `StoredArtifact` records in the
`KPROV\0\x01\0` payload format. Provenance strings and artifact metadata are
preserved as supplied; they are not normalized or assigned additional
provenance semantics by this crate.
Decoders validate format markers, declared lengths, UTF-8, object identifiers,
timestamps, trailing bytes, and canonical file-envelope metadata. File metadata
lengths are rejected against their canonical limits before copying. Other
variable-size codec allocations use checked size arithmetic and fallible
reservation; allocation or capacity failures are returned as `Error`. The crate
performs no logging or transport translation.