Benzene Specification

The language-neutral definition of Benzene — the concepts, wire contracts, and conformance fixtures every language port implements. New here? Start with the overview, then work through the documents below.

• The Core Specification
  • Overview — how the spec is organized and the two conformance levels (Core vs. the Cloud Service Profile)
  • Design Principles — "opinionated but optional": the adoption ladder, and the rule that every steer must be replaceable
  • Core Concepts — the abstract model: pipeline, context, message handler, topic, result, lifecycle
  • Wire Contracts — the message envelope, header conventions, the status vocabulary, and its per-protocol (HTTP/gRPC) mappings
  • Transport Bindings — what a transport adapter must satisfy, with every existing binding as a worked example
  • Mesh Contracts — service self-description, trace events, and collector topics for fleet-wide visibility
  • Contract Document — the derived .spec.json a service exposes at /benzene/spec: its shape, the topic-scoping and schema-closure rules a client generator must implement, and the cross-language contractHash algorithm
  • Payload Schema Versioning — versioning a topic's request/response shape independently of handler versioning
  • Porting Guide — concept-vs-idiom mapping and suggested order for implementing Benzene in another language
  • Port Quality Standards — the Definition of Done for a language port: the DX-champion-in-the-loop workflow and the quality gates a unit of port work must clear
  • Conformance Fixtures — the language-neutral test fixtures every implementation runs to prove conformance
• The Cloud Service Profile
  • Cloud Service Profile — the named conformance target (requirements R1–R8) that guarantees mesh, Spec UI, and fleet tooling work on a service with no per-service negotiation