WIT-first contract compiler for stable Rust, protobuf, JSON Schema, and versioned adapters
witforge turns one hand-written WIT package into the artifacts the two sides of a contract need:
It is not a runtime, transport, or WASM guest-binding generator. Non-Rust consumers use the
emitted .proto with their normal protobuf toolchain; Rust consumers can use the generated plain
types directly.
Install the current release:
cargo install witforge-cli --version 0.5.0 --locked
witforge --version
From this repository, before or after publication:
cargo run -p witforge-cli -- --version
The examples below use witforge; replace it with cargo run -p witforge-cli -- when working
from a checkout. Every command on this page runs from one working directory, the one that
contains my-contract/, and the test suite runs them in this order.
Create a root with a version directory:
my-contract/
wit/
v0.1/
contract.wit
mkdir -p my-contract/wit/v0.1
Save a small contract as my-contract/wit/v0.1/contract.wit. The package version must match the
directory name, and an interface and a world cannot share a name:
package example:hello@0.1.0;
interface greeter {
record greeting {
text: string,
}
greet: func(name: string) -> greeting;
}
world hello {
export greeter;
}
At this point, contract.wit is the only file in v0.1. Do not create wire.lock by hand.
Create the lockfile, assign wire numbers, and validate the contract:
witforge lock my-contract/wit/v0.1 --first
witforge check my-contract/wit/v0.1
witforge lock --first creates my-contract/wit/v0.1/wire.lock. Commit contract.wit and the
generated wire.lock together. The lockfile is append-only: generated protobuf field numbers and
method ids must never change.
Generate each projection:
witforge rust my-contract/wit --out my-contract/generated/rust
witforge proto my-contract/wit --out my-contract/generated/proto
witforge schema my-contract/wit --out my-contract/generated/schema
witforge glue my-contract/wit --out my-contract/generated/glue \
--plain-root crate::generated::rust --proto-root crate::generated::proto
--plain-root and --proto-root are Rust module paths, not output directories. The glue emitter
uses them to reference the plain types and the prost types generated from the .proto schema.
Every generator supports --check, which writes nothing and fails if committed output differs:
witforge rust my-contract/wit --out my-contract/generated/rust --check
witforge proto my-contract/wit --out my-contract/generated/proto --check
witforge schema my-contract/wit --out my-contract/generated/schema --check
witforge glue my-contract/wit --out my-contract/generated/glue \
--plain-root crate::generated::rust --proto-root crate::generated::proto --check
witforge.tomlPut the repeated paths in a project file, my-contract/witforge.toml:
version = 1
[project.hello]
root = "wit"
[project.hello.rust]
out = "generated/rust"
# serde = true # opt in to Serialize/Deserialize derives
[project.hello.proto]
out = "generated/proto"
[project.hello.schema]
out = "generated/schema"
[project.hello.glue]
out = "generated/glue"
plain-root = "crate::generated::rust"
proto-root = "crate::generated::proto"
Then each generator only needs the project file:
witforge rust --config my-contract/witforge.toml
witforge proto --config my-contract/witforge.toml
witforge schema --config my-contract/witforge.toml
witforge glue --config my-contract/witforge.toml
If the file has more than one project, add --project NAME. Paths inside the file are relative to
the file itself. Explicit CLI paths override configured paths, and the command-line-only form
continues to work. --serde or --no-serde overrides the Rust section’s serde setting; the
generated code then requires the consumer’s serde crate with derive.
A contract change is a new version directory, never an edit to a released one. Keep every released version in the tree:
my-contract/wit/
released # lists v0.1
v0.1/
contract.wit
wire.lock
v0.2/
contract.wit
wire.lock
When v0.1 ships, record it as released. released lists frozen version directories, one per
line:
echo v0.1 > my-contract/wit/released
Start the next minor as a copy of the previous version, lockfile included. The copied lockfile is
what carries the field numbers, method ids, and reservations forward; never start a later minor
with lock --first:
mkdir my-contract/wit/v0.2
cp my-contract/wit/v0.1/contract.wit my-contract/wit/v0.1/wire.lock my-contract/wit/v0.2/
Edit my-contract/wit/v0.2/contract.wit. Change the package version to 0.2.0 first: until it
matches the directory name, every command refuses the directory. Then make the change. Add new
members with defaultable types when possible:
package example:hello@0.2.0;
interface greeter {
record greeting {
text: string,
language: option<string>, // old values become None
tags: list<string>, // old values become an empty list
}
greet: func(name: string) -> greeting;
}
world hello {
export greeter;
}
Assign numbers to the new members and validate the draft against the released lockfile:
witforge lock my-contract/wit/v0.2 --against my-contract/wit/v0.1/wire.lock
witforge check my-contract/wit/v0.2 --against my-contract/wit/v0.1/wire.lock
Regenerate. With two versions in the root, witforge rust also writes convert.rs:
witforge rust --config my-contract/witforge.toml
witforge proto --config my-contract/witforge.toml
witforge schema --config my-contract/witforge.toml
witforge glue --config my-contract/witforge.toml
convert.rs holds old-to-new and new-to-old adapters. Old-to-new conversion fills an added
option with None and an added list with an empty list. New-to-old conversion drops members
the older version does not have. Missing required older members are reported as
ConversionError::MissingMember; added or removed cases are reported as
ConversionError::UnknownCase. A required, non-defaultable addition is refused by conversion
generation.
Do not edit a released version’s WIT, lockfile, or generated Rust module. witforge lock refuses
a released directory, and check and the generators fail when a released WIT file no longer
matches its lockfile. No witforge command notices a released WIT file and its lockfile edited
together: that needs a history check in CI, such as this repository’s
ci/check-release-freeze.sh.
Compare a draft with the previous version before merging it:
witforge diff my-contract/wit/v0.1 my-contract/wit/v0.2
witforge diff my-contract/wit/v0.1 my-contract/wit/v0.2 --json
witforge diff my-contract/wit/v0.1 my-contract/wit/v0.2 --check # exits 1: see below
--check fails on wire-, source-, or generated-API-breaking changes. It exits 1 for the change
above: the two added fields keep every wire number and convert from old values, but Rust code
that constructs a Greeting has to be updated, so diff reports them as source- and
API-breaking. --json is the complete diff report. diff also reports a note when a shared record type’s generated new-to-old converter
is guaranteed to fail because the older version requires a member the newer version removed; the
notes do not change the change counts or --check result. To make any command’s diagnostics
machine-readable, add --format json or --format sarif; the catalogue is in the
diagnostics specification.
For CI, asamarts/witforge publishes an Action that
installs the matching release and can run the same checks; see
the Action specification.
Use the protobuf output with the normal generator for the target language:
protoc-gen-go;ts-proto or another protobuf generator;protoc, grpcio-tools, or another protobuf generator;The generated language type is only the protobuf projection. Proto3 cannot express every WIT
decode rule: narrow integers need range checks, required optional and message fields need
presence checks, enums are closed, and variant/result oneof values must select a known case.
Implement those rules in the non-Rust adapter and test invalid as well as valid values. The
Non-Rust implementation guide specifies the complete profile.
witforge intentionally does not duplicate wit-bindgen’s runtime WIT bindings or own transport
framing. The stable protobuf numbers and JSON Schema are cross-language contract artifacts, not a
complete application protocol.
The current subset is deliberately pure and synchronous:
<major>.<minor>.0;use aliases, lists, options, and results are
supported;deps/ layout
are supported as package-qualified references; worlds may import and export dependency
interfaces, and glue covers dependency types and functions. See the
dependency specification.Run witforge check for the exact diagnostic. The
design overview has the
full contract model and the reasons for each refusal.
A version directory may use standard deps/ packages. Put the dependency under
wit/v0.1/deps/, declare its package, and import its types or interfaces normally:
package example:app@0.1.0;
interface api {
use example:shared/types@0.1.0.{item};
get: func() -> item;
}
world plugin {
import example:shared/types@0.1.0;
}
witforge rust, proto, schema, and glue generate the dependency bindings alongside the
local output. See the
dependency specification
for the generated files and dependency glue layout.
Serde is opt-in per project:
[project.demo.rust]
out = "generated/rust"
serde = true
The default generated output is unchanged; enabling Serde requires the consumer’s serde crate
with the derive feature. --serde and --no-serde override the configuration.
Plain Rust Serde, Draft 7 JSON Schema, and proto3-JSON project the same WIT values differently:
start-byte becomes start_byte;start-byte, requires every record property, and permits
null for option<T>;startByte), decimal strings for 64-bit integers, and normally
omits an absent optional value;Choose one authoritative JSON profile. Keep an explicit application adapter when an existing protocol differs, and do not validate one projection with another projection’s schema. See JSON projections for the full comparison.
examples/single — one
version, all four generators, config-driven.examples/evolved — released
v0.1 plus draft v0.2, lock continuity and generated conversions.wire.lock missing: for the first version use witforge lock <dir> --first; for a new
minor copy the previous lockfile and use --against.witforge lock, review the printed added, reserved, updated, and
dropped entries, and commit the result.--check, review the diff, and commit
the result.