Optional + Default Record Fields

[jaredramirez]

This PR implements optional + defaulted record fields.

Types

• Each RecordField gets a Presence variable, thats flex, present, optional, & default: DefaultId. When uniyfing, flex < required < default, where the rightmost wins. optional is incompatible with required/defaulted.
  • Note that defaulted must win/merge over required
  • Each defaulted expr must be literal
  • Unifying two defaulted fields of the same type with different default values produces an error
• When unifying two records, missing optionals/defaults get pushed into record extensions. Then, we add new unification logic to allow {} to unify with a record that contains only optionals/defaults

Lowering:

• Optional fields have the are mapped to a structrual tag union representation [#Missing, #Present(a)]
• Defaulted fields keep the plain required-field repr (inline slot) since the field is always present at runtime. The default's identity is part of the field's concrete (monotype) identity, so two records that differ only in a default are distinct concrete types — that's what keeps derived codecs sound (a required record shaped like a defaulted one must not share its parser)

JSON derived codec:

• When encoding an optional field, if the field is not present in the roc record (ie is #Missing) then the field is omitted in the encoded JSON. Conversely when decoding, if the field is not present in the JSON, then it is set as #Missing in the roc record. Note that if the JSON field is presen but null, decoding fails! null != optional but not present
• When decoding a default field, if the field is not present in the JSON, then the default value is used to construct. As with optional fields, an explicit null fails decoding. Encoding a defaulted field always emits it (including when it equals the default)

Open Questions:

Given the following:

mk_job : { num_threads : U8 } -> Job

config_a : { num_threads : U8 }
config_a = { num_threads : 2 }

config_b : { num_threads : U8, name ?: Str }
config_b = { num_threads : 2 }


main = || {
  job_a = mk_job(config_a)
  job_b = mk_job(config_b)
}

Results in mk_job having two concrete versions after monomorphization. When we instantiate mk_job with config_b, the record that mk_job accepts must be widened to accept the record+optional fields. This works just fine, but may be unintuiative to the user who is trying to reason about what is getting monomorphized in this code & could result in many versions of the same function.

One way to solve this is to introduce polarity-based restriction, to disallow record widening in the input position. Ths would cause job_b = mk_job(config_b) to be an error. But we would loose some expressiveness. IMO we should do this polarity-based restriction, for the same reason we restrict let-generalizationin Ayaz's Let's Not write up.

---

Implements optional record fields (name ?: Type, accessed with .?) and defaulted record fields (name : Type ?? default, construction-optional) end-to-end: parse → canonicalize → check → checked module output → monotype/LIR lowering → interpreter, dev, wasm, and llvm backends — including derived JSON codecs. The authoritative design lives in design.md ("Field Kinds (All-Dynamic Optional Fields)" and "Defaulted Fields"). The branch is a commit stack on current main: the squashed feature commit, the ?: syntax commit, follow-ups for kind defaulting, literals-only defaults, optional update/destructure, cleanup, the nominal field-kind resolution fix, the reserved slot labels, width-absorption eval pins, and JSON codec derivation.

Syntax

	syntax	meaning
optional field	{ name ?: Str }	may be missing at runtime (tagged slot); read with .?name → Try(Str, [MissingField])
optional access	record.?name	works only on optional fields; .? on a required/defaulted field is rejected
defaulted field	{ count : U8 ?? 10 }	construction may omit it (compiler fills the default); at runtime an ordinary required field, read with .count

Access chains collapse to one flat Try per chain: o.?b.?c : Try(C, [MissingField]) (never nested), a required segment after an optional one rides the Ok path, the first missing slot short-circuits to the shared MissingField, and one ?? fallback covers the whole chain. The former :? spelling recovers with a did-you-mean diagnostic and the formatter migrates it to ?:.

Checking

• Annotations pin kinds concretely in every position (no polarity split); kind unification is the join lattice from the summary above; width absorption into closed rows is opt-in (only a kind resolved optional/defaulted from an annotation absorbs — undetermined kinds never do, so typo'd extra fields stay errors).
• List literals seed their element expectation from the annotation, so xs : List({ a ?: U8 }); xs = [{ a: 1 }, {}] typechecks — as does the defaulted equivalent.
• Default values must be literals (numbers, interpolation-free strings, tags, and lists/records/tuples built only from literals — judged at canonicalization). Every default-cycle shape is impossible by construction; the previous reference-based rules are deleted as subsumed. Defaults must be concrete; two separately-written defaults never merge.
• .? on a required/defaulted field is judged at every generalization boundary, so let-polymorphism can't launder a receiver past the check.
• Kind defaulting is a real solver pass: a still-flex field kind commits to required at module finalize; scheme interiors deliberately stay flex so instantiations can still join ?: annotations.
• Record update sets optional fields with creation semantics; record destructure binds optional fields as Try via a deferred kind-directed judgment (nested { x: Ok(y) } patterns match the Try value, including in match branches with guards).
• Nominal-backed records resolve field kinds through their declaration's backing row across module views (tri-state resolution: found / scheme-interior→required-equivalent / absent→invariant — never a guess), with argument substitution for generic nominals' slot types.

Checked module output + lowering

• CheckedRecordField carries a field kind (required / optional / defaulted + default identity); .? access segments publish their mode; archived default expressions ship in CheckedBodyStore.default_exprs and are restored at every construction site that omits the field, then constant-folded via compile-time roots.
• Optional slots lower as the closed structural union [#Missing, #Present(τ)] whose labels are compiler-reserved (# starts a comment in source, so no user tag can spell them — same namespace as #interp_0 idents). Sorted variant order matches the unprefixed names, so the ABI discriminant contract (variant 0 = missing) is unchanged, and slot recognition below checking (inspect, codecs) is an exact lossless read-back rather than a shape test. A user-annotated [Missing, Present(τ)] is an ordinary distinct tag union.
• Glue computes the identical slot layout from the published kind (by variant index — labels never surface), so ?: stays legal across the Host Symbol ABI.
• Inspect renders a present slot as the plain field value and a missing one as <missing>.

Derived JSON codecs

?: fields participate in derived Json encode/parse as the slot-kind sibling of the existing Try(τ, [Missing]) convention (which is unchanged):

• Encode: a #Present slot emits its field with the payload's encoder; a #Missing slot omits the field entirely.
• Parse: an absent JSON field materializes #Missing for a ?: field and fills the archived default for a ?? field; a present one parses at the payload/inline type. Explicit null stays an error for both. Records with required fields still demand MissingRequiredField(Str) in the format error row exactly as before; a record whose fields can all self-fill validates with a closed error row.
• Pinned by test/cli/JsonOptionalFieldKinds.roc (absent/present parse, .? read-back, encode omit/emit, nested round-trip) on interpreter + dev backends.

Semantics under discussion: width-absorption polarity

Today a closed annotated parameter row absorbs a caller's extra optional fields by widening its instantiation: f : { b : Str } -> Str accepts a { a ?: U64, b : Str } value (unification merges — no subtyping — and bodies monomorphize per solved instantiation, so layouts always agree; pinned across all four backends by three eval tests marked semantics-under-debate). The open language question is whether absorption should be polarity-restricted to construction sites only (absorb only into a literal's still-unbound row), which would make every specialization of f an exact instantiation of its annotation and reject wide-value-into-narrow-param calls. The type store already distinguishes the two row provenances (record_unbound vs committed record), so the restriction is a guarded condition on the absorption path plus a diagnostic — a small change once the semantics are decided. Until then this PR ships the permissive merge semantics.

Review rounds

Two full review passes are folded in (18 self-review comments + two adversarial-review rounds). Fixes landed on-branch: nominal-backed construction/update panic (kind lookup now walks nominal backing; required-kind fallback removed), dead snapshot-tool helper deleted, default_exprs deinit, dev-backend sub-word immediate stores (sizes 1–7), and kind-directed composition with upstream's new RecordUpdate monotype node. Filed upstream: #10416, #10483 (top-level destructure publication gap; near-term REPL guard included here), #10576 (generic update supplying an optional field — checker-admitted, loud postcheck invariant; needs a checker-side decision). Two earlier filings are closed: #10415 (obsoleted by the literals-only default restriction) and #10466 (the x64mac ZigGlue HFA mismatch root-caused upstream as a Zig compiler ABI bug, tracked by #10392).

Deferred (documented in design.md)

• Width-absorption polarity restriction (see above — pending language decision).
• Unsetting a field ({ ..r, x: _ }) — designed, not implemented.
• { field ?? fallback }-style destructure sugar.
• Exhaustiveness analysis skips sub-pattern spaces behind an optional field's Try binder (typing still validates them).
• Optional fields: generic record update supplying an optional field panics postcheck (scheme-interior kind) #10576 (generic update × optional field, checker-side fix).

Testing

Full unit suite green (4135); snapshot corpus regenerated with no drift; multi-backend eval suite green including 60+ optional/defaulted runtime tests (heap payloads + ARC, nested chains, generic passage, Try interop, record update slot copying, structural equality, Inspect rendering, mixed-presence lists, width absorption on all four backends); JSON codec CLI tests; wasm static-lib suite; cross-module and serialization round-trip tests pin the published kinds; canonical-key agreement verified byte-for-byte between solver and checked representations.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VnRxmioksj59fxuAkqpPvV

[greptile-apps]

Too many files changed for review (217 files, 100 file limit).

Bypass the limit by tagging @greptile-apps to review.