Proposals

Ideas for the project from authors and contributors, triaged for fit. A proposal captures a direction and its trade-offs. Once the team commits to one, the rationale and rollout move to a Design record and the proposal is marked accepted.

How a proposal is written

Each page opens with a Status: line, house style — a status in bold followed by ·-separated notes:

• draft — being written, not yet up for discussion
• under discussion — open for feedback
• accepted — the team is going this way; see the linked Design record
• implemented — accepted and shipped; the page says where what shipped differs from what it proposed
• rejected / superseded — with a note saying why, and by what

Proposals may compete: two pages proposing different answers to the same question. They are grouped together below and stay open until one is accepted; the others become rejected or superseded with a one-line reason.

By area

Runtime & codegen repository organization

How the per-language surface — codegen, libgen, runtime — is split across repositories. Two competing proposals, read to the same shape:

• Proposal B — split by language — one repo per target holds that language's codegen, libgen, and runtime together. accepted — adopted directly by the design record.
• Proposal A — split by concern — generation stays one repo; runtime graduates heavyweight language runtimes to their own repos. rejected — superseded by B; kept for the reasoning.

Org-wide decision record: Design → Runtime & generation repository structure.

How generators are built

Whether generation stays hand-written Rust that pushes strings, and what the alternatives are worth. Five proposals, read to the same shape:

• Proposal A — a shared resolution kernel — a symbol/module layer in comline-codegen; generators map a resolved model to syntax. under discussion — the recommendation of the group.
• Proposal B — templates — per-language template files replace push_str. under discussion — complementary to A, not a substitute.
• Proposal C — syntax trees — build an AST per target and pretty-print it. under discussion — one cheap component recommended, the whole not.
• Proposal D — target-language plugins — protoc-style: each generator is a program in its own language. under discussion — blocked by the wasm playground, not rejected.
• Proposal E — adopt an existing model — translate Comline IR to Smithy and inherit its generators. under discussion — assessed, not recommended as a basis.

Shared runtime core

How ten or more language runtimes stay correct, conformant and fast without writing the same logic in each. One Rust protocol core every language binds, codecs generated from one plan, and every language proven against the Rust reference. One proposal in three stages, read in order:

• Stage 1 — verification: differential fuzzing against the Rust reference, and benchmark gates, in every language's CI. accepted, stage 1 in progress: the reference process, fuzz targets and benchmark gates are built for Rust.
• Stage 2 — core interface: the handshake, framings and connection state machine behind a stable C ABI and WASM, built from one crate. accepted, steps 1–3 built: the core changes, the C ABI at 0.1 (reference), and its vectors, fuzzing and benchmarks. Bindings are next: TypeScript through wasm. The ABI stays 0.x until the 1.0 announcement.
• Stage 3 — generated codecs: native per-type codecs and protocol glue rendered from one plan in the codegen kernel. under discussion.

Versioning

• Schema compatibility: which schema changes are breaking, measured by the wire and by the names consumers use, with formats and framings versioned and declared by the package so the rules can depend on them. under discussion.
• Language target versions: what the version in rust#1.70.0 means, how it picks a generator, and how feature support and output depend on it, proven by conformance at each version where they change. implemented.

Extensibility

• Extending the call system: how developers bring their own wire formats, framings, transports and dispatchers, with official encodings defined through the same public mechanism as third-party ones. under discussion.

Marking a given-up guarantee

How a schema marks an extension that gives up one of Comline's guarantees between peers, the role unsafe plays in Rust. Four competing proposals, read to the same shape:

• Proposal C — @unverified, one marker: core infers which guarantees are affected. accepted, with the consumer's acceptance recording that set.
• Proposal A — @waives, per guarantee: names each guarantee given up. rejected: repeats what core computes.
• Proposal B — @assumes, per guarantee: names what the author assumes holds instead. rejected: same, and its direction can be misread.
• Proposal D — keep @unchecked: the original name. rejected: says neither who nor what.

Connections

• Connections: what a connection carries beyond one client calling one server: calls in both directions on a transport-independent core, per-connection state and interceptors, several protocols per connection. accepted; calls both ways and several protocols built.
• Package wire defaults: a wire key in config.idp for the package's framing and format, datagram@2 as the built-in framing, a new packed C-struct-like format packed@1 as the built-in format, and a generated Services struct with a package-level serve. shipped.

Packet protocols

• Packet dispatch: message-oriented packet protocols (families, explicit ids, phases, @provider for direction), with addressing in the schema, generated dispatch tables, and an official configurable framing. under discussion, partly decided.

Function ids

How an explicit function id is written. Two competing proposals:

• Proposal A — an @id annotation. accepted, with assignment on build and a reuse guard.
• Proposal B — a prefix on the declaration, from the 2024 proposal. rejected.

Phase syntax

How phases are written. Two competing proposals:

• Proposal A — an enum plus annotations: phases are an ordinary enum; @phase and @transition on the declarations. accepted.
• Proposal B — a phase block: a new declaration lists each phase in one place. rejected: a new construct and a second table.

Tagged unions

Whether "one of several shapes, with a tag" is a feature of enum or of union. Three competing proposals, under discussion:

• Proposal A — a union declaration: members written like struct fields, tagged with @id. leaning.
• Proposal B — enum variants that carry data, as in Rust and Swift.
• Proposal C — both.

Tooling

• Automatic documentation — an optional tool that documents a user's own schemas and packages — their structs, enums, protocols, errors — from the IR and its docstrings, with the CAS supplying per-version docs and a generated changelog. draft.