Coercions, seals, and nested drafts

[joeldrapper]

What this does

Three related changes, one commit each:

Literal::Coercion and Literal::Seal

Splits the property pipeline into two explicit stages:

• Coercions normalize input before the type check. They run only at input boundaries — the initializer, writers, and draft assignment — never on final-value paths like from_props or marshal_load.
• Seals fix a value's final representation (freezing it, for example), running after any coercion and before the type check, on every constructing path — the initializer, writers, and from_props, which takes values that may never have been through construction and computes defaults itself. They don't run on marshal_load: a loaded object was constructed (and sealed) before it was dumped, and the frozen state recorded at dump is what gets restored. Seals must be idempotent and type-preserving.

Both compose with >> and <<. Composing two coercions yields a coercion; composing a coercion into a seal yields a seal whose coercion runs first. Any arrangement that would run a coercion after a seal is rejected at composition time — and Seal is deliberately not callable, so raw_proc >> seal fails immediately instead of silently demoting the seal.

Properties take either through the existing block slot — the proc built by Literal::Coercion() / Literal::Seal() carries its pipeline structure, and prop splits it into the property's coercion and seal. Collection generics compose too: Literal::Array(String) >> Immutable.

The built-in Immutable and DeepImmutable become seals; NilIfEmpty becomes an explicit coercion.

Frozen state through Marshal

Marshal.load rebuilds contained objects unfrozen, so a property value that was frozen when dumped (a _Frozen-typed value, for example) came back mutable and failed the load-time type check. marshal_dump now records which values were frozen (payload version 2) and marshal_load re-freezes them before checking. Version 1 payloads still load, and old readers ignore the new payload element.

Nested drafts

A draft slot typed as a Literal::Properties class now also accepts a draft of that type (or a subtype), and finalize builds nested drafts depth-first — unless the drafted type's property wanted a draft as-is, in which case it stays one. Finalize never mutates the draft: finalizing twice builds two independent values.

Under the hood, relaxation is a first-class type: _DraftState(T) matches what a slot typed T may hold while drafting — one walk that relaxes both representation (stripping _Frozen) and finality (widening T to accept drafts of T). Draft properties are _Union(Undefined, _DraftState(T)), so errors and introspection name what a draft slot actually accepts. The union member is Literal::Draft::Type, a lightweight matcher with Literal::Draft(T)'s === semantics but no generated class, so recursive types (a Person with a Person property) don't recurse forever at draft-class definition. Draft coercions skip nested drafts the way they skip Undefined — a draft isn't the drafted type's input yet; it meets the coercion's output contract at finalize through its own construction.

Deliberately out of scope: drafts inside collections (_Array(T), Literal::Array(T)). Widening element types would force a type-driven relax/restore pair over the whole type algebra; holding that until there's a real need.

Testing

Each commit is individually green against the full suite (3172 → 3172 → 3176 → 3192 tests). New tests cover marshalling frozen-state round-trips, version 1 payload compatibility, and nested drafts: slot acceptance (subtypes, through _Nilable), depth-first finalize with nested defaults, inner missing-property errors, purity, draft-typed slots keeping their drafts, and coercion passthrough. Known gap: the >>/<< composition error paths have no direct tests yet.

🤖 Generated with Claude Code

Canonical draft classes

Literal::Draft(Foo) now returns the same generated class on every call until Foo's properties change, instead of a fresh class per call. The cache is keyed by the class's schema in an ObjectSpace::WeakKeyMap, with each entry recording the schema's sorted-properties snapshot — an array the schema replaces on every mutation, so its identity changes exactly when the schema does. Reopening a class invalidates lazily with no mutation tracking, and anonymous classes (and their stale drafts) stay collectable.

Building through drafts

Draft#finalize takes an optional block, yielded the draft after any props are assigned and before the value is built — for last touches like conditional assignment. Draft classes gain build — construct, yield, finalize in one call, with arguments going to the constructor and the block to finalize — and Literal::DataStructure.build layers the same onto Data and Struct themselves (structs are mutable, but required properties still make incremental construction impossible without a draft):

Foo.build(id: 1) do |draft|
  draft.name = name if bar?
end

Review follow-ups from the Codex findings are also in: deferred property types relax lazily (and the draft union now puts Undefined first so unresolved forward references never materialize early), and composed coercion stages run in the property context via instance_exec, with the composition algebra now under direct test.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e729cf03b7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".