Designing Builder Surfaces

A good builder surface starts from the domain, not from the generic build machinery.

For a service builder, the domain might include runtime, entrypoint, port, health path, and service protocol. For a native code generator, the domain might include schema, compiler, defines, artifact kind, and generated outputs. The public constructor should ask for those domain concepts and lower them into the shared builder program.

Start From The Artifact

Ask what the builder promises to produce. A runnable package, a generated source tree, a static library, a CLI, a service unit, or a descriptor bundle each imply different outputs, operations, tools, and runtime descriptors. The artifact tells you which of those the builder needs.

Name The Vocabulary

Use domain names in the public API and avoid exposing generic mechanics when a domain term is clearer. A service builder should ask for a port or a healthPath before it asks the user to construct a low-level runtime protocol value.

Keep The Constructor Small

A constructor should accept the smallest set of choices that define the build. Everything derived from those choices should be generated by the builder. This keeps the user-facing API stable while the internal program becomes more capable.

Lower Into Operations

The constructor is responsible for lowering domain choices into operations. That lowering is where tools, generated files, descriptors, output declarations, and materialization steps enter the program. The domain fields capture what the user said, and the operations capture what the build does.

Expose Standard Views

A production builder should expose the same standard views during development. Validation, dependency graph, dry-run, plan-view, describe, introspect, and materialize together become the builder's debugging and documentation surface.

Use Ornaments For Domain Shape

An ornament extends the base builder spec with domain-specific fields. Use one when a builder needs a typed domain shape but should still behave like a normal metaBuilder program. The ornament adds data only. It never extends the operation alphabet, and a typed forget map projects the ornamented builder back to the shared shape while keeping its program intact. That is what lets a domain builder stay fully compatible with every standard view.