switchback-traits

[!WARNING] Early prototype while exploring design and aiming for equivalence with protobuf-mdbook, while expanding scope through traits and intermediary on-disk representation.

This is not ready for adoption, nor even stable at a v1alpha1 yet. You'll want to keep eyes on the repository for development.

A lot of this is clanker driven, so vetting a good human read through pass hasn't been completed yet.

The seam of the switchback-rs toolchain.

switchback-traits owns the trait spine and the in-memory model that every parser and every renderer depends on, with no dependency on any contract family, output format, or serialization implementation:

• ContractFamily and Contract — parser-side identity and loaded contract views; ContractFamily::supported_protocols and ContractFamily::default_protocol declare which protocol slugs a family may attach during populate
• ProtocolAttachment — transport envelope (protocol_id + payload bytes) on contract and entity nodes; see ADR 0011
• Renderer / SyncRenderer, SwitchbackCodec / SyncSwitchbackCodec, LinkExtractor, LinkFormatter — renderer-side and serialization seams
• ReferenceManual and related model types — the lossless in-memory switchback graph
• Options, LinkContext — shared option and link-index data shapes (logic deferred)

Protocol vs contract family: contract family is spec grammar (OpenAPI, Protobuf, AsyncAPI); protocol is invocation/transport semantics (http, grpc, custom). Families populate protocols[] on contract and entity nodes; renderers decode attachments via switchback-protocols rather than re-parsing OperationBody.signature.

I/O traits follow ADR 0002: async-primary APIs with sync-secondary counterparts for external compatibility (when a caller cannot host an async runtime or wrap the async traits). All seam types are Send / Sync as appropriate for async pipelines.

Helper implementations (slug, link check, paths, companion discovery, prose escaping) live in follow-up work; this crate ships traits and model types only.

See the workspace Glossary for terminology.