This format is independent of repository, object, and workspace formats. Adding a gateway changes none of their bytes. The gateway root contains:
SCRIBE_GATEWAY: exact UTF-8 bytesscribe-gateway\n2\n.LOCK: exclusive OS ownership lock.routes.redb: redb 4 database containingroutesandinstancestables.status.json: disposable observation snapshot, never authoritative routing.
The root holds no credentials or trust material. The gateway's TLS key and its
service-account credential file ([tls] key and [tls] credential in the
gateway configuration) are not part of
this format; keep them outside the root (scribe-ctl refuses them inside it).
routes maps a repository address string to a scribe_format::gateway::RouteRecord.
On a TLS gateway every instance serves one auth namespace and the address is
<namespace>/<name>, so the same storage name in two namespaces is two routes
and the namespace of a route is the prefix of its key. A plaintext gateway has
no namespaces and keys routes by the bare name. Ledger v1 keyed every route by
bare name; a v1 root is refused, not migrated. The record itself is unchanged:
| Field | Encoding |
|---|---|
| Record version | u8 = 1 |
| Instance name | u16 LE byte length, then UTF-8; 1–64 ASCII letters/digits/hyphens/underscores |
| Storage compression | u8: 0 none, 1 LZ4 |
| Has repository ID | u8: 0 or 1 |
| Repository ID | 16 exact bytes, present only when the preceding flag is 1 |
| Conflict flag | u8: 0 or 1 |
Unknown versions, invalid flags, invalid compression, invalid names, truncated
records, and trailing bytes are rejected. A record without an ID is a durable
pending name reservation. A conflict flag prevents routing that name. On open,
every route's instance must still be configured and must still serve the
namespace in the route's key; otherwise the gateway refuses to start.
Byte fixtures and strict decoding tests are in
gateway.rs.
instances maps a configured instance-name string to its exact 16-byte data-root
incarnation. An identity is pinned after successful inventory. A different
identity at the same name or the same identity under another name is rejected.
Both placement reservations and completed assignments commit with
Durability::Immediate. Payload encoding, authentication, inventory collection,
and upstream requests happen outside database write transactions. Routing state
is never inferred from the disposable JSON snapshot. Unsupported ledger versions
are refused; there is no ledger migration command.