Builder-First Construction Migration

KlumAST 4.0 changes how model creation works internally: it configures Builders first and then materializes one completed, structurally immutable model graph. Most schemas and model scripts that already use generated factories should continue to work without changes:

def config = Config.Create.With {
    project("api") {
        url "https://example.invalid/api"
    }
}

Do not rewrite working schemas preemptively. Compile the schema, run a representative model, and follow the targeted diagnostics if KlumAST finds a construct that crosses the new Builder lifecycle boundary.

Migration Checklist

1. Compile the Schema

Run the build or compilation task that normally compiles your @DSL classes. Fix ordinary compilation errors first, then use this guide for Builder-first diagnostics:

Public Builder Contracts

Generated accessors and relationship creators always expose Foo_DSL.Builder<Foo>, never the hidden Foo$Builder implementation. This also applies when a forward relationship target is unresolved during transformation, whether the models share a source file or compile from separate source files. (See: GeneratedDslSupportSpec#'projects same-source forward relationship Builders into the public namespace'.)

For same-project IntelliJ source completion, refresh the IDEA-only Foo_DSL mirrors through the Schema plugin and reload the Gradle project. The refresh materializes one root-owned GDSL resource directory and registers it with every Schema module; the packaged contributor then supplies source-level static Foo.Create as Foo_DSL.Factory and Foo.Template as Foo_DSL.TemplateScope, without exposing hidden implementation classes. The capitalized members use the version-sensitive internal GDSL bridge described in Gradle Onboarding; it does not add bytecode or independent read-only semantics. This is IDE metadata only: neither the GDSL root nor mirrors become compiler, package, or downstream inputs.

// Schema.groovy
@DSL
class Parent {
    Child child
}

@DSL
class Child {}

In generated signatures and IDE source mirrors, Parent_DSL.Builder uses Child_DSL.Builder<Child> for child.

Relationship creator overloads

Generated owned-relationship creators accept their named-value map without a configuration closure. This applies when a Schema Developer or Builder-first extension statically types the receiver as the public Foo_DSL.Builder contract; the same overloads appear in IDEA-only source mirrors. Keyed, dynamic-Class, typed-Create Factory, collection, and map relationship creators retain their established return types and type metadata.

(See: BuilderProjectionDocumentaryTest#'configures an owned relationship through a public Builder without an empty closure'.)

@CompileStatic
static void configure(Workspace_DSL.Builder<Workspace> workspace) {
    workspace.repository([url: 'ssh://git@example.test/catalog.git'])
}

Use the closure-taking form only when further child configuration is needed; omitting it is equivalent to passing an empty configuration closure.

Builder-phase Type Checks

Relationships are Builders until the graph materializes. A completed-model instanceof check therefore belongs in a completed-model validation callback rather than in construction-time code. (See: BuilderFirstMigrationDocumentaryTest#'keeps completed-model type checks in validation'.)

@Validate
void validateCompletedService() {
    assert service instanceof Service
}

Builder-phase Factories

Create.With, Create.One, and Create.From are root factories: they return a completed model and own a complete Construction session. In a mutator, mutating lifecycle method, or Builder-retargeted annotation closure, create the owned child in the active session instead:

@Mutator
void supplySource() {
    source = ProductSource.Create.AsBuilder().With(name: 'default source')
}

The returned Builder must be attached to an owned relationship. Do not use Create.AsBuilder() for an independent root model; use the ordinary root factory outside Builder-phase code instead.

Factory Methods Exposed Through Create

Public methods declared on a custom Factory are exposed through Create, so they must be instance methods. Keep Factory itself static; this rule applies only to its public methods. Private, protected, and package-private static helpers remain internal to the Factory. Model-level static converters remain outside the Factory contract.

(See: BuilderFirstMigrationDocumentaryTest#'exposes an instance Factory method through Create'.)

@DSL
class ServicePlan {
    String name

    static class Factory extends KlumFactory.Unkeyed<ServicePlan> {
        protected Factory() { super(ServicePlan) }

        ServicePlan standard(String name) {
            Create.With(name: name)
        }
    }
}

assert ServicePlan.Create.standard('catalog').name == 'catalog'

Map Configurator Overrides

Factory maps preserve method-first configuration. When a Builder has both a writable outboxUrl field and an explicit outboxUrl(String) mutator, Create.With(outboxUrl: value) calls the mutator. This makes intentional overrides work consistently across Create.With, Create.AsBuilder().With, Templates, and automatic creation.

@DSL
class Mailbox {
    String outboxUrl

    @Mutator
    String outboxUrl(String value) {
        // Normalize, validate, or coordinate related Builder state.
        value
    }
}

Mailbox.Create.With(outboxUrl: 'https://example.invalid')
Mailbox.Create.With(setOutboxUrl: 'https://example.invalid') // explicit direct field assignment

KlumAST warns when this exact one-argument @Mutator override returns the field value or its Builder, because map configuration will choose the method. A void mutator is unambiguous and remains silent. A non-void return unrelated to the field or its Builder is rejected at the mutator declaration; rename it or make it setter-like. Methods without a same-named writable field retain their existing map-method fallback without a diagnostic.

2. Compile and Run a Representative Model

Compile and execute at least one real root configuration. A unit test that calls Config.Create.With is usually the simplest repeatable migration check; an existing root script is equally suitable. A project-less script can also obtain KlumAST with @Grab, but the complete standalone-script setup will be documented separately.

Build owned children through the generated method on that root Builder, so the entire configuration shares one lifecycle. (See: BuilderFirstMigrationDocumentaryTest#'builds a representative deployment through one Builder lifecycle'.)

def deployment = Deployment.Create.With {
    environment 'production'
    service {
        image 'catalog:1.0'
    }
}

assert deployment.service.image == 'catalog:1.0'

The generated Foo_DSL.Builder<Foo> interface now types copyFrom for an active Builder of the same model. In a @Default, @AutoCreate, or Create.AsBuilder().With callback, use that public Builder type instead of suppressing static checking. Runtime still rejects sealed and cross-session Builder sources.

3. Run the Full Model Test Suite

Pay particular attention to lifecycle callbacks, validation, ownership and construction paths, sorted collection comparators, Templates, serialization, and Jackson inputs. These areas intentionally distinguish between the construction-time Builder graph and the completed model graph.

Optional Mechanical Starting Point

The best-effort convenience script performs only a small set of mechanical 3.x-to-4.0 edits. It is not a KlumAST migration tool: it does not promise a compiling project, understand application semantics, or replace the checklist below. Run it only from the schema module directory—the Gradle subproject containing the Schema's src/main and src/test sources—not from a multi-module project's top-level directory. That module must be in a clean, disposable Git worktree. Review its diff immediately, then compile, run a representative model, and fix the remaining compiler errors with this guide.

Use this order: update the schema module to the target KlumAST version, run the script, inspect the diff, then commit it as a deliberate migration starting point or revert it. Continue with the Template migration guidance, this checklist, and compilation. The canonical creation/application example is executable in TemplatesDocumentaryTest#'applies one scoped template to multiple service configurations'.

It rewrites public schema-annotation imports, changes the deprecated @DelegatesToRW spelling to @DelegatesToBuilder, migrates Layer 3 annotation imports such as @AutoCreate, copy annotations such as @Overwrite, and KlumModelException/KlumValidationException imports. It also converts only current-target Groovy Validator reporting/suppression calls and direct type-qualified Template creation calls:

The Template rewrites are intentionally narrow. The script leaves Foo.Template.With and WithAll scoped application, variables such as type.Template.Create, dynamic/custom calls such as holder.Service.Template.Create, method references, comments, and quoted/script content unchanged. It recognizes imported direct model names (and direct nested model names), not fully qualified types or expression/property chains. It preserves the argument text of a recognized direct call, but does not promise that the result compiles.

It intentionally does not rewrite internal packages, ValidatorBase, validation result readers, explicit-target Validator calls, fully qualified type references, Builders, factories, relationships, lifecycle structure, or any other semantic migration.

Do not broaden this script by guessing package destinations or rewriting unresolved compiler errors. The compilation and model checks are the handoff from mechanical edits to the actual migration.

Builder Lifecycle Field Types

Builder lifecycle code preserves ordinary declared collection and map element types. A statically checked @Default or @AutoCreate method can use the inferred type directly; no source-side cast is required:

(See: ModelPhasesDocumentaryTest#'preserves simple collection types in Builder lifecycle code'.)

@DSL
class CustomerRoster {
    List<String> customers = ['central:primary']
    String primaryCustomer

    @Default
    @CompileStatic
    void selectPrimaryCustomer() {
        customers.each { String customer ->
            primaryCustomer = customer.split(':', 2)[0]
        }
    }
}

Detailed Migration Rules

• Replace direct construction with generated factories. Completed DSL Objects are not client-constructed.
• Move post-construction model.apply { ... } calls into the original Create.With { ... } callback, a Template, or another factory input. Completed models expose no generated apply method.
• Stop calling KlumInstanceProxy.getProxyFor(model). The deprecated compatibility adapter accepts Builders only. Completed model technical state belongs to the Model companion and supported public utilities.
• KlumRwObject and $_RW are removed in 4.0. Name generated Foo_DSL.Builder<Foo> interfaces and use @DelegatesToBuilder; an inherited Child_DSL.Builder<Child> remains a Parent_DSL.Builder<Child> and has the one KlumBuilder<Child> capability required by Builder-producing APIs. The legacy @DelegatesToRW annotation remains a deprecated source alias. Builders do not expose the former getDSLInstance() or getRwInstance() identity aliases.
• Build all owned children through the parent Builder lifecycle. Do not call Child.Create.With directly from inside a parent construction callback: that would start a second lifecycle, which is forbidden. Use the generated child method on the parent Builder. For polymorphic relationships, child(ConcreteChild) remains the dynamic Class-selection form; child(ConcreteChild.Create) provides an exact static Builder delegate. Passing Create here is contextual selection in the current session, not a root factory invocation.
• Pass an existing completed DSL Object only to a FieldType.LINK relationship. Completed objects cannot become newly owned composition. Use a Template when an existing object is intended as a reusable recipe; applying it rehydrates fresh Builders.
• Treat copy sources by identity: ordinary models and Maps are value-only, marked Templates add immutable recipe replay, and only same-session unsealed Builders add an ephemeral snapshot of pending actions. Never use a sealed or cross-session Builder as a live recipe.
• Keep deferred Builder actions below phase 40. applyLater and scheduleApplyLater now fail immediately at INSTANTIATE or later, including during Template replay.

Implementation Details

The migration checklist above is sufficient for ordinary Schema and Model work. For the Builder/materialization boundary, generated producer projection, lifecycle state, and the public-versus-synthetic generated API, see Behind the Curtain#builder-first-materialization.

Templates, Serialization, and Jackson

Templates remain client-facing DSL Object recipes. Every owned node created in Template mode has persistent Template identity, while pre-existing ordinary LINK targets retain their identity. Every application copies the recipe into a fresh ordinary Builder graph, so ownership, paths, lifecycle callbacks, and validation belong to the recipient construction.

A Template applyLater recipe must address the fresh Builder through its closure delegate. Capturing a Builder in a local variable or holder is rejected because a completed recipe must not retain construction state. The complete graph of other captured recipe values must be serializable so the detached recipe remains serializable. Java serialization preserves the Template companion and immutable recipe state, but never Builders, Construction sessions, scopes, or mutable recipe collections. Ordinary completed models retain no deferred actions.

The internal generated $proxy field uses a sealed common Model/Template companion solely for cross-package generated linkage. It is not client API. Use KlumObjectSupport.of(object) for supported completed-object paths, structure, and stored validation; do not build integrations on companion classes or raw metadata. The supported construction-string getter is getConstructionPath(); see #390 and ADR 0006.

getValidation().getSubtreeResults() returns the target's result and every stored result in its owned subtree, including clean results without issues. Use KlumObjectSupport.getValidation() directly; the preliminary Validator result readers are removed in 4.0 rather than retained as deprecated adapters.

Jackson import now binds externally owned data to public Builder configuration through resolved property metadata. Missing input preserves source initializers and later defaults; present values, null, and containers replace current Builder state authoritatively between PostCreate and PostApply. Derived output can be exposed as Jackson read-only output and is recomputed by the single normal lifecycle rather than rebound.

Rename migrated JSON with @JsonAlias while keeping the new @JsonProperty name canonical. Configured naming strategies, mixins, ignore/access rules, and unknown-property policy are resolved by Jackson. Ambient Templates, @Overwrite, and copyFrom no longer affect JSON input. See Jackson Integration and ADR 0009.

LINK import requires an explicit reference schema, property conversion, or lifecycle resolution. Put @JsonIdentityInfo on the target type and @JsonIdentityReference(alwaysAsId = true) on each LINK for standard Jackson identity handling. Backward and forward ids resolve against completed targets or Builders allocated in the same import session. Inline objects are not accepted as LINK input. Output must choose its own explicit representation and may use a custom deliberate inline serializer when the external format requires it.

Marked Templates are rejected as JSON values so recipe actions cannot be silently lost; rehydrate a fresh ordinary model before serialization. Jackson views, formats, inclusion, Simple Value codecs, mixins, and polymorphic owned types remain supported, but creator, model-setter, foreign Jackson Builder, owned completed-model deserializer, and managed/back-reference annotations cannot replace the Klum Builder lifecycle.

Do not treat JSON/YAML output as a Klum persistence or round-trip format. Completed models serialize through ordinary Jackson APIs, KlumAST adds no wire metadata, and external version properties remain Schema-controlled data. Each importer operation accepts one input and owns one lifecycle; YAML documents and exported projections never establish Jackson-owned composition or cross-input overwrite semantics.