kcode-k1-persons-wire 0.1.0

Exact wire-v1 encoding for K1 person actions
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

# K1 persons wire

This library owns the exact stateless wire-v1 representation of K1 person actions. It performs no registration, persistence, authorization, discovery, listing, submission, retry, callback correlation, locking, or I/O.

## Public API

```rust
pub use kcode_k1_person_types::PersonId;
pub use kcode_k1_txn_ordering::TxId;

pub struct PersonsWire { /* private exact bytes */ }
impl PersonsWire {
    pub fn create(name: String) -> Result<Self, String>;
    pub fn update(person: PersonId, name: String) -> Result<Self, String>;
    pub fn resolve(canonical: PersonId, alias: PersonId) -> Self;
    pub fn as_bytes(&self) -> &[u8];
}
pub fn decode(payload: &[u8]) -> Result<kcode_k1_persons_projection::PersonAction, String>;
```

`PersonsWire` implements `Clone`, `Debug`, `Eq`, and `PartialEq`, and is `Send + Sync`.

## Wire-v1 contract

Create is `[1, 1, name...]`, update is `[1, 2, person_id..., name...]`, and resolve is `[1, 3, canonical_id..., alias_id...]`. Every person ID is exactly the 12 bytes of its transaction ID. Create totals 3 through 130 bytes, update totals 15 through 142 bytes, and resolve is exactly 26 bytes.

Create and update preserve exact UTF-8 names and return the projection's exact name-validation errors. Decode validates the version, kind, total length, UTF-8, and projection semantics. Every malformed payload returns exactly `invalid persons wire payload` without including payload content. Resolve is infallible, and no alternate or legacy wire is accepted.

## Performance

`PersonsWire::create` is not yet benchmarked; it performs O(name bytes) work with one wire-payload allocation and no I/O.
`PersonsWire::update` is not yet benchmarked; it performs O(name bytes) work with one wire-payload allocation and no I/O.
`PersonsWire::resolve` is not yet benchmarked; it performs bounded work with one fixed 26-byte wire-payload allocation and no I/O.
`PersonsWire::as_bytes` is not yet benchmarked; it is constant-time and allocation-free with no I/O.
`decode` is not yet benchmarked; it performs O(payload/name bytes) work, allocates one `String` for create or update, and performs no I/O.