Native Wire reference
This page is a compact index for agents and implementers. The normative source is docs/native-wire-v1.md; the complete machine contract is /native-wire-v1.json. Both are versioned with the repository. LNW/1 is experimental, opt-in, and disabled by default.
Envelope
| Item | Value |
|---|---|
| Magic | ASCII LKW1 (4c4b5731) |
| Version | 1 |
| Byte order | Unsigned big-endian |
| Header | 40 bytes |
| Body | metadata TLVs, payload, CRC32C (4 bytes) |
| Text | shortest-form UTF-8, NUL-free |
| Unknown optional field | Skip |
| Unknown critical field | Reject the stream (UNSUPPORTED_FIELD) |
| Downgrade / code reuse | Forbidden |
Header offsets are fixed and must not be inferred from a language ABI:
| Offset | Size | Field |
|---|---|---|
| 0 | 4 | magic |
| 4 | 2 | version |
| 6 | 1 | frame type |
| 7 | 1 | flags |
| 8 | 8 | connection sequence |
| 16 | 8 | request ID |
| 24 | 4 | stream ID |
| 28 | 2 | operation/error/control code |
| 30 | 2 | reserved (zero) |
| 32 | 4 | metadata length |
| 36 | 4 | payload length |
Defaults and security
| Limit or policy | Default |
|---|---|
| Metadata / DATA payload / frame | 64 KiB / 1 MiB / 1,114,156 bytes |
| Streams / connections | 128 / 1,024 |
| Stream / connection window | 4 MiB / 16 MiB |
| Auth skew | 300 seconds (maximum 5 minutes) |
| Replay state | 1,024 principals × 256 nonces per principal |
| Upload admission | security.max_concurrent_uploads = 128, process-wide |
| Upload idle / maximum duration | 2 minutes / 24 hours per stream |
| Auth retry hint maximum | 600,000 ms |
| Non-loopback TLS | TLS 1.3 + hostname verification |
User metadata is an ordered, duplicate-preserving user namespace. Internal SSE-C and Object Lock fields are typed and separate. The effective lockwelld mask excludes SSE_C (128); use S3 for genuine SSE-C. Admin bit 16 and operation range 0x1000–0x10ff are reserved and unimplemented.
Frame types
| Code | Type | Role |
|---|---|---|
0x01 | HELLO | Client version, capabilities, receive limits |
0x02 | WELCOME | Server selection and intersection |
0x03 | AUTH | Access-key timestamp, nonce, transcript proof |
0x04 | AUTH_OK | Tenant, session, expiry, capabilities, effective limits |
0x05 | AUTH_ERROR | Bounded authentication failure |
0x10 | REQUEST | Starts one operation on an odd client stream |
0x11 | DATA | Flow-controlled bytes |
0x12 | END | Closes one direction |
0x13 | CANCEL | Cancels the stream context |
0x20 | RESPONSE | Starts a successful response |
0x21 | ERROR | Typed terminal response |
0x30 | WINDOW_UPDATE | Grants stream or connection credit |
0x31 / 0x32 | PING / PONG | Eight opaque liveness bytes |
0x33 | GOAWAY | Drain or protocol reason and last accepted stream |
0x34 | CLOSE | Authenticated close acknowledgement |
Capabilities
| Bit | Name | Advertised by lockwelld |
|---|---|---|
| 1 | BUCKETS | yes |
| 2 | OBJECTS | yes |
| 4 | PAGINATION | yes |
| 8 | MULTIPART | yes |
| 16 | VERSIONING | yes |
| 32 | OBJECT_LOCK | yes |
| 64 | TAGS | yes |
| 128 | SSE_C | no (no enforced native path) |
| 256 | SIGNED_CAPABILITY | yes |
| 512 | TRACE_CONTEXT | yes |
| 1024 | CORS | yes |
| 2048 | NOTIFICATIONS | yes |
| 65536 | ADMIN (reserved) | no |
Operations
| Code range | Operations | Required capability |
|---|---|---|
0x0001–0x0002 | CAPABILITIES, READINESS | authenticated discovery |
0x0100–0x0105 | bucket CRUD and versioning | BUCKETS |
0x0200–0x0207 | object CRUD, ranges, copy, versions, batch delete | OBJECTS |
0x0300–0x0305 | multipart create/part/list/complete/abort/list | MULTIPART |
0x0400–0x0402 | tags get/put/delete | TAGS |
0x0500–0x0503 | retention and legal hold | OBJECT_LOCK |
0x0600 | signed capability mint | SIGNED_CAPABILITY |
0x0700–0x0702 | bucket CORS get/put/delete | CORS |
0x0710–0x0712 | bucket webhook notifications get/put/delete | NOTIFICATIONS |
Clients must not send an operation until its capability is selected. The complete field and document schemas are in the JSON registry; response metadata includes status, ETag, version, length/type, request ID, traceparent, timestamps, delete-marker, retention/legal-hold, and ordered user metadata.
Errors and retry contract
| Code | Name | Typical handling |
|---|---|---|
0x0103 | AUTH_REPLAY | terminal; do not retry the proof |
0x0300 | RATE_LIMITED | retry only from a fresh connection with fresh credentials/proof when marked retryable |
0x0301 | UNAVAILABLE | bounded caller retry when operation/body is replay-safe |
0x0302 | DEADLINE_EXCEEDED | terminal for the stream; partial upload state is removed |
0x0303 | CANCELLED | caller cancellation; no implicit replay |
0x0204 / 0x0205 | RETENTION_DENIED / LEGAL_HOLD_DENIED | authorization/policy denial |
0x0207 / 0x0208 | CHECKSUM_MISMATCH / TOO_LARGE | fix input or limits; do not retry unchanged |
AUTH_ERROR fields are retryable (required bool), retryAfterMillis (optional, ≤600000), and bounded message (≤512 bytes). Error frames contain safe messages and correlation only; secrets and payloads are never reflected.
Implementations and source links
- Native-wire architecture and rollout
@kelphect/sdk-nativeguide (Node 22+, Bun 1.4+; browser denied)@kelphect/sdk-solidstartguide (SolidStart v2; Node/Bun Nitro server presets only)@kelphect/sdk-nextjsguide (Next.js 16.3.3–16.x; Node/Bun-compatible server runtime only)- Spring Boot starter guide (JDK 25, Spring Boot 4.1.1)
- Raw protocol Markdown on GitHub
- Shared fixtures