GSoC 2026 Proposal Draft: Support boolean and enum types

[Piyush-Goenka]

Project Proposal

1. Project Title

Support Boolean and Enum Types in LowType - Mentored by @maedi

---

2. Project Size

Small (~90 hours)

This scope is appropriate because the project extends LowType's existing type-expression pipeline instead of introducing a new parser or a new external integration. The work is focused and well-bounded:

• implement a dedicated Boolean complex type
• implement a parameterized Enum[*values] type
• validate enum defaults during Class Load
• add tests and documentation

The proposal deliberately keeps parser changes in Lowkey out of scope and concentrates on LowType evaluation and validation.

---

3. Project Length

Small project (~90 hours) over 8 weeks.

---

4. Abstract

LowType provides optional inline type annotations and runtime type checking in Ruby without introducing a build step. This project will add two important missing type constructs: a strict Boolean complex type and a parameterized Enum[*values] type for closed sets of literal or mixed Ruby values. The implementation will follow LowType's existing three-phase architecture: File Load via Lowkey parsing, Class Load via expression evaluation and method redefinition, and Runtime validation per call. The final result will let users express common Ruby constraints such as flags and finite allowed-value sets with natural LowType syntax, backed by tests and documentation.

---

5. Problem Statement

Today, LowType already supports standard Ruby classes such as String, Integer, Array, and Hash, along with framework-aware or domain-aware complex types such as Tuple, Status, and Headers. However, two highly practical type constructs are still missing:

• Boolean, even though it is already documented as an unreleased complex type
• Enum[*values], which is currently only at concept stage

These gaps matter because they represent common real-world Ruby constraints:

• method flags are often strictly true or false
• many APIs and internal methods only allow one value from a known set

Without first-class support, users must approximate boolean behavior with ad hoc unions and cannot express closed-value sets as part of LowType's inline type syntax. That weakens LowType's goal of being a lightweight, expressive, Ruby-native typing tool.

There is also an architectural requirement specific to Enum: invalid defaults should fail early during LowType's Class Load evaluation phase rather than only when the method is called later at runtime. Supporting this cleanly is important for correctness, predictability, and developer feedback.

---

6. Proposed Solution

Architecture Fit

This work fits LowType's current architecture and does not require a parser rewrite.

The current flow is:

1. File Load — Lowkey parses Ruby source and stores method parameter / return expressions as strings in proxies.
2. Class Load — LowType.included loads those proxies, Low::Evaluator evaluates the stored Ruby expressions, and Low::Redefiner redefines methods around the evaluated expressions.
3. Runtime — Low::TypeExpression#validate! validates method arguments, local typed values, accessors, and return values on each call.

That flow already exists in the codebase:

module LowType
  def self.included(klass)
    file_path = Low::FileQuery.file_path(klass:)
    file_proxy = Lowkey.load(file_path:)
    class_proxy = file_proxy[klass.name]

    Low::Evaluator.evaluate(method_proxies: class_proxy.keyed_methods)

    klass.include Low::ExpressionHelpers
    klass.extend Low::ExpressionHelpers
    klass.extend Low::TypeAccessors
    klass.extend Low::Types

    klass.prepend Low::Redefiner.redefine(method_proxies: class_proxy.instance_methods, class_proxy:)
    klass.singleton_class.prepend Low::Redefiner.redefine(method_proxies: class_proxy.class_methods, class_proxy:)
  end
end

The key design choice in this proposal is to add Boolean and Enum as values that can already be evaluated during Class Load, instead of extending Lowkey's parser. Since Lowkey stores the original expression string and Low::Evaluator later runs:

expression = new.instance_evaluate(proxy: param_proxy)
param_proxy.expression = cast_type_expression(expression:, method_proxy:)

supporting Boolean and Enum[...] is primarily an evaluation/validation problem inside LowType.

Expected User-Facing Syntax

The syntax targeted by this proposal is:

def publish(enabled: Boolean | false)
end

def paint(color: Enum["red", "orange", "yellow"] | "red")
end

state = type Enum[:draft, :published, 200] | arg

The goal is for these expressions to work anywhere LowType already accepts type expressions:

• method parameters
• typed accessors
• local type() expressions

I tested nested type expressions first, and the current array validation path is already recursive. That suggests nested forms such as Array[Boolean] or Array[Enum[:draft, :published]] should likely work once Boolean and Enum[...] are integrated into the existing type-expression machinery. I would still keep explicit tests for those cases.

A. Dedicated Boolean Complex Type

Boolean is already listed in lib/types/complex_types.rb, but the current placeholder uses the generic factory:

Boolean = TypeFactory.complex_type(Object)

That is not a correct model for Ruby booleans. true and false are instances of TrueClass and FalseClass, so Boolean needs a dedicated implementation instead of a generated subclass of Object.

A likely implementation is:

module Low
  module Types
    class Boolean
      class << self
        def match?(value:)
          value.equal?(true) || value.equal?(false)
        end

        def display
          'Boolean'
        end
      end
    end
  end
end

This keeps the external type surface clean:

• users write Boolean, not TrueClass | FalseClass
• Boolean | nil remains possible through the existing union/default-value syntax
• error rendering uses display rather than overriding Ruby's core inspect or to_s

Expected usage:

def feature_flag(enabled: Boolean)
  enabled
end

def cache(fetch: Boolean | false)
  fetch
end

flags = type Array[Boolean] | [true, false, true]

B. Parameterized Enum[*values]

Enum[...] would be a parameterized type object. LowType already hints at this pattern through Status[...], where calling [] returns an object rather than the bare Status class. Enum[...] should fit that broader model rather than introducing a one-off special case.

The syntax should be:

def paint(color: Enum["red", "orange", "yellow"] | "red")
end

result = type Enum[:draft, "published", 200] | arg

I would represent Enum[...] as a definition object created during Class Load:

module Low
  module Types
    class Enum
      class Definition
        attr_reader :values

        def initialize(values:)
          raise AllowedTypeError, 'Enum requires at least one allowed value' if values.empty?

          @values = values.freeze
        end

        def match?(value:)
          @values.any? { |allowed| allowed == value }
        end

        def display
          "Enum[#{@values.map(&:inspect).join(', ')}]"
        end
      end

      class << self
        def [](*values)
          Definition.new(values: values)
        end
      end
    end
  end
end

Note that display is used instead of overriding Ruby's core inspect or to_s methods. This keeps debugger output intact while still giving a clean user-facing representation for error messages.

This design has a few advantages:

• supports mixed values naturally: Enum[:symbol, "string", 123]
• allows membership checks by normal Ruby equality (==)
• works with richer object instances if users want object-valued enums
• keeps the syntax Ruby-native, since Enum[...] is just a class method call evaluated during Class Load
• fits the broader parameterized-type pattern already hinted at in LowType

Expected valid usage:

def publish(state: Enum[:draft, :review, :published] | :draft)
  state
end

def retryable(code: Enum[408, 429, 500, 503])
  code
end

color = type Enum["red", "orange", "yellow"] | incoming_color

C. Type Recognition in TypeQuery

At the moment, LowType recognizes:

• plain classes
• listed complex types via COMPLEX_TYPES
• typed arrays and hashes

There is an existing gap here. Low::Types::COMPLEX_TYPES.include?(expression) checks against the type class itself — for example Status. But when a user writes Status[200], that returns a value object rather than the Status class. So COMPLEX_TYPES.include?(Status[200]) returns false, meaning Status[200] may not currently be recognized as a type expression. Enum[...] would have the same problem if handled naively.

The fix is to introduce a generalized typed_definition? method, as maedi suggested, so parameterized LowType objects are recognized through a shared mechanism rather than one explicit check per type. To keep runtime validation coherent, I would also separate match-based complex-type recognition from structural typed-array/hash recognition:

def type?(expression)
  basic_type?(expression:) ||
    complex_type?(expression:) ||
    typed_array?(expression:) ||
    typed_hash?(expression:)
end

def complex_type?(expression:)
  Low::Types::COMPLEX_TYPES.include?(expression) ||
    typed_definition?(expression:)
end

With that split, complex_type? stays focused on types that are expected to answer match?, while typed_array? and typed_hash? remain their own structural cases. The exact implementation of typed_definition? should be confirmed with mentor during Community Bonding. The important part is that it should recognize parameterized LowType objects such as Status[...] and Enum[...] via one shared protocol or internal convention, not via a brittle class-name check.

D. Runtime Validation in TypeExpression

The main validation path already exists in Low::TypeExpression#validate!, which delegates element-by-element checks to type_matches_value?.

Following maedi's suggestion, if Status is made to support match? at the type level, type_matches_value? can be simplified toward:

def type_matches_value?(type:, value:, proxy:)
  if Low::TypeQuery.complex_type?(expression: type)
    return type.match?(value:)
  elsif type.instance_of?(Class)
    return type == value.class
  elsif type.instance_of?(::Low::TypeExpression)
    type.validate!(value:, proxy:)
    return true
  end

  false
end

This is cleaner than the previous version because:

• complex types are handled first, before plain class checks
• no need for respond_to?(:match?) — the contract guarantees match? exists on every complex type
• works uniformly for Boolean, Enum::Definition, Status, and any future parameterized type

Typed arrays and hashes would remain on their existing validation path and would no longer be grouped under complex_type? in this design, since they are not themselves match?-based types. The core direction is to make parameterized types and complex types converge on the same match? contract.

E. Class Load Validation for Invalid Enum Defaults

The issue requires invalid enum defaults to fail early — during Class Load, not at runtime when the method is first called.

Expected invalid example:

class Example
  include LowType

  def paint(color: Enum["red", "orange", "yellow"] | "blue")
    color
  end
end

The default "blue" is not in ["red", "orange", "yellow"] and should be rejected immediately when LowType evaluates the expression, not later.

The current evaluator stores expressions but does not eagerly validate defaults. I would add an explicit validation step after the expression is built:

expression = cast_type_expression(expression:, method_proxy:)
param_proxy.expression = expression

if enum_expression?(expression) && !expression.required?
  default = expression.default_value
  default = default.value if default.is_a?(ValueExpression)
  expression.validate!(value: default, proxy: param_proxy)
end

Even if type recognition is generalized, I would initially scope this eager validation to enum-backed expressions so that existing semantics for other defaults are not unintentionally changed. If mentor feedback suggests generalizing this further, that can be discussed during implementation.

F. Error Rendering and Developer Feedback

LowType's proxies already build error messages from @expression.valid_types. The goal is to make all parameterized type objects render cleanly through that existing path using their display method, without special-casing any specific type.

Current-style errors look like:

"Invalid argument type 'Integer' for parameter 'greeting'. Valid types: 'String'"

Expected enum/boolean output would be:

"Invalid argument type 'String' for parameter 'color'. Valid types: 'Enum[\"red\", \"orange\", \"yellow\"]'"
"Invalid argument type 'NilClass' for parameter 'enabled'. Valid types: 'Boolean'"

The valid_types method should use display generically for any type that responds to it, rather than special-casing Enum::Definition or any other specific class:

def valid_types
  types = @types.map do |type|
    case type
    when Array
      "[#{type.map { |subtype| valid_subtype(subtype:) }.join(', ')}]"
    else
      type.respond_to?(:display) ? type.display : type.inspect.to_s.delete_prefix('Low::Types::')
    end
  end

  types << 'nil' if @default_value.nil?
  types.join(' | ')
end

This means:

• Enum::Definition renders via display → Enum["red", "orange", "yellow"]
• Boolean renders via display → Boolean
• Any future parameterized type automatically gets clean rendering by implementing display
• Ruby's core inspect is never overridden, so debugger output remains intact

G. Test Strategy

I would mirror the current testing style rather than introducing a new spec structure.

Unit-level coverage:

• a Boolean spec modeled after spec/units/types/status_spec.rb
• an Enum spec for Enum[...] construction, matching, and formatting
• focused tests for TypeQuery and TypeExpression behavior where needed

Feature-level coverage:

• fixture classes under spec/fixtures/
• end-to-end specs under spec/features/
• cases for method parameters, type(), nested arrays, invalid defaults, and error messages

Example fixture/spec pair for eager enum validation:

# spec/fixtures/enum_invalid_default.rb
class EnumInvalidDefault
  include LowType

  def paint(color: Enum["red", "orange", "yellow"] | "blue")
    color
  end
end

# spec/features/enum_spec.rb
it 'fails during class load when enum default is invalid' do
  expect do
    load 'spec/fixtures/enum_invalid_default.rb'
  end.to raise_error(Low::AllowedTypeError)
end

Using load rather than require_relative for these negative class-load cases would make the failure explicit and repeatable within the test suite.

Main Areas of the Codebase

Based on my codebase study, the project will primarily touch:

• lib/types/complex_types.rb
• lib/queries/type_query.rb
• lib/definitions/evaluator.rb
• lib/expressions/type_expression.rb
• new files under lib/types/, likely boolean.rb and enum.rb
• spec/units/types/status_spec.rb as the reference pattern for type-specific specs
• spec/features/ and spec/fixtures/ for end-to-end behavior coverage

Scope Boundaries

The following are intentionally out of scope for this proposal:

• boolean coercion from strings or integers
• parser refactors in Lowkey
• new syntax beyond the current Enum[...] and existing type-expression model
• broad redesign of all complex types
• unrelated changes to return-type or framework adapter behavior unless required by the new types

---

7. Project Deliverables

The expected deliverables are:

• a dedicated strict Boolean complex type
• a parameterized Enum[*values] type supporting mixed Ruby values
• Class Load validation for invalid enum declarations/defaults
• runtime validation for boolean and enum type expressions
• clear error messages for enum mismatches, including allowed values
• unit tests for the new types and validation rules
• feature tests covering method parameters, defaults, and type() usage
• documentation updates in the README and changelog entries as appropriate

If the implementation integrates naturally with all existing expression entry points, support should work consistently anywhere LowType already accepts type expressions, including method parameters, typed accessors, return types where relevant, and type().

---

8. Timeline / Milestones

Community Bonding

• discuss final internal representation of Enum[*values] with mentor
• confirm typed_definition? implementation and match? contract with mentor
• confirm error-message shape and default-validation behavior
• prepare a small design note and convert requirements into concrete test cases
• ensure local development environment is fully set up against main branch

Week 1 — Boolean: Implementation + Tests

• implement failing specs for strict Boolean behavior
• replace the existing TypeFactory.complex_type(Object) placeholder with a dedicated Boolean class in lib/types/boolean.rb
• register it in lib/types/complex_types.rb
• wire through evaluation and runtime validation
• complete unit and feature coverage for method parameters, defaults, and type()

Week 2 — Enum: Core Implementation

• implement failing specs for Enum[*values]
• implement Enum::Definition class in lib/types/enum.rb
• implement typed_definition? in Low::TypeQuery
• extend complex_type? to use typed_definition?

Week 3 — Enum: Validation + TypeExpression

• simplify type_matches_value? using Maedi's cleaner version
• ensure Status has a class-level match? to satisfy the shared contract
• add feature coverage for enum use in methods and type()
• support mixed values and membership checks via ==

Week 4 — Class Load Validation for Enum Defaults

• implement Class Load validation for invalid enum defaults
• verify that bad enum expressions fail during evaluation, not on first method call
• add targeted tests for early failure behavior using load in specs

Week 5 — Error Messages + Edge Cases

• implement display on Boolean and Enum::Definition
• update valid_types to use respond_to?(:display) generically
• test edge cases involving symbols, strings, integers, and object instances
• verify nested expressions like Array[Boolean] work out of the box

Week 6 — Review + Refinement

• review full implementation against mentor feedback
• fix any issues surfaced during review
• ensure behavior is consistent with existing LowType conventions throughout

Week 7 — Documentation + Cleanup

• complete README updates for Boolean and Enum usage
• add changelog entries
• clean up and refactor internal code as needed

Week 8 — Buffer

• buffer week for review feedback, bug fixes, and polish
• finalize all deliverables
• prepare final report and submission materials

---

9. Related Work

Typed boolean and closed-value enum constructs already exist in most modern typed languages. TypeScript supports boolean and literal unions such as "red" | "orange" | "yellow". Python provides similar expressiveness through typing.Literal["red", "orange"]. In both cases, these are primarily static-analysis or compile-time constructs.

In Ruby, the closest existing approaches are RBS/Steep, Sorbet, and dry-types:

• RBS and Steep provide static type checking, but typically require separate signature files and an external checking workflow
• Sorbet offers gradual typing, but also introduces a larger annotation and tooling model
• dry-types provides rich runtime constraints, but through an explicit DSL rather than LowType's inline method-signature style

LowType's approach is different: it evaluates type expressions inline during Class Load, using normal Ruby method default-value syntax and then performs optional runtime validation. That makes it especially well suited to Ruby's dynamic and open-class model. Adding Boolean and Enum as complex types extends this existing design rather than introducing a new syntax, a separate schema language, or a parser-heavy type layer.

---

10. Previous Contributions

LowType — PR #23: Support empty hash return type when key => value defined

While studying the codebase in preparation for this proposal, I identified and fixed a bug where empty hash literals ({}) were not recognized as valid typed-hash expressions in union type expressions. For example:

type_accessor nodes: Hash[String => TrieNode] | {}

This would fail before the fix. The changes touched lib/queries/type_query.rb and lib/expressions/type_expression.rb — the same files central to this proposal — and included regression coverage in the existing fixture and feature spec files.

Codebase Study

Beyond the PR, I read through the full LowType source including:

• lib/definitions/evaluator.rb
• lib/expressions/type_expression.rb
• lib/queries/type_query.rb
• lib/types/complex_types.rb
• the full spec layer under spec/units/ and spec/features/

I also studied the architecture split between Lowkey (parsing) and LowType (evaluation/validation) introduced in the recent main branch refactor that has not yet been released as a gem.

Mentor Discussion

Discussed design choices for Boolean and Enum directly with @maedi, covering strict boolean semantics, mixed-value enum support, and the Class Load vs Runtime validation phase distinction.

---

11. About You

My name is Piyush Goenka. I am a second-year B.Sc. Computer Science student at BITS Pilani.

I was drawn to LowType because it solves a real problem elegantly — bringing optional runtime type safety to Ruby without a build step or a separate schema language. Most typing solutions in Ruby feel like they are fighting the language. LowType feels like it belongs in it. That philosophy of staying lightweight and Ruby-native is what made this project stand out to me over other GSoC ideas.

Open Source

I am an active open source contributor. I contributed extensively to the Palisadoes Foundation — the organization behind the Talawa project, a modular open source platform used by community-based organizations worldwide. My contributions were consistent and substantial enough that I was made a maintainer of the organization. This means I have real experience navigating large unfamiliar codebases, following contributor conventions, writing reviewable code, and taking responsibility for the quality of a shared project.

Achievements

I won Smart India Hackathon (SIH), India's largest national-level hackathon, which required building and shipping a working technical solution under a tight deadline — a skill directly relevant to a GSoC project with fixed weekly milestones.

I am comfortable navigating real codebases I did not write, contributing before I fully understand every detail, and communicating clearly with maintainers. This project is a natural next step for me.

---

12. Availability

Timezone: IST (UTC+5:30)

Hours per week: I can commit 10–12 hours per week during the coding period, which is sufficient for a small (~90 hour) project over 8 weeks. I have no internships, travel, or other major commitments planned for this summer, so GSoC will be my primary focus during the coding period.

Exam conflicts: BITS Pilani's academic calendar may overlap slightly with the start of the GSoC period. Any such overlap is manageable and will not affect my ability to meet weekly milestones. I will flag any schedule constraints to the mentor during Community Bonding well in advance.

---

13. Communication Plan

I plan to communicate in a lightweight and consistent way throughout the project:

• Weekly updates — post a short progress note every week covering what was completed, what is next, and any blockers
• Design questions early — raise implementation questions on Discord or GitHub Discussions before writing code
• Small reviewable PRs — keep implementation work in focused, incremental pull requests so feedback is easy to act on
• Document decisions — use PR descriptions and issue comments to record why technical choices were made, not just what changed
• Early escalation — notify the mentor immediately if a blocker, scope question, or schedule conflict arises

I am on Discord and reachable on GitHub. IST (UTC+5:30) is my timezone and I can adjust communication windows to overlap with the mentor's availability during Community Bonding.

---

14. Additional Notes

This proposal is intentionally scoped as a focused improvement to LowType's complex type system rather than a general parser or type-system overhaul. The work is bounded, the extension points are clear, and the existing Status implementation provides a solid model to follow.

If I complete the planned deliverables ahead of schedule, I would use the remaining time for:

• additional edge-case coverage and error message polish
• documentation examples for the README
• small cleanup or refactoring directly related to the implemented feature set
• exploring other open ideas in LowType after discussing with the mentor

Beyond GSoC

GSoC is not the end goal for me — it is a starting point. I am genuinely interested in LowType as a project and in the broader problem of making Ruby more expressive without sacrificing its dynamic nature. I intend to continue contributing after the summer, whether that means tackling other open issues, reviewing PRs, helping new contributors understand the codebase, or working on the next feature. I want to be a long-term contributor to this project, not just a summer one.

[maedi]

A lot of thought has gone into this and it shows, thanks!

nested expressions such as Array[Boolean] or Array[Enum[:draft, :published]]

Type checking is recursive (I think), so hopefully this just works out of the box. Just write a test first and see if it passes

B

def inspect
  "Enum[#{@values.map(&:inspect).join(', ')}]"
 end

alias to_s inspect

Overriding core Ruby methods may cause a situation where a future debugger goes crazy because they don't see the full object when they inspect the object. Let's come up with another method name like "display"

C

def complex_type?(expression:)
  Low::Types::COMPLEX_TYPES.include?(expression) ||
    expression.is_a?(Low::Types::Enum::Definition) ||
    typed_array?(expression:) ||
    typed_hash?(expression:)
end

I think a generalised typed_definition method would be good, that checks if the type has a Definition or ComplexTypes or ComplexValues class within it... something like that.

Low::Types::COMPLEX_TYPES.include?(expression) is probably not considering Status[200] a complex type, so there's probably a bug here that a general method that recognises Status[] and Enum[] would solve.

D

def type_matches_value?(type:, value:, proxy:)
  if type.instance_of?(Class)
    return type.match?(value:) if Low::TypeQuery.complex_type?(expression: type)
    return type == value.class
  elsif Low::TypeQuery.complex_type?(expression: type) && type.respond_to?(:match?)
    return type.match?(value:)
  elsif type.instance_of?(::Low::TypeExpression)
    type.validate!(value:, proxy:)
    return true
  end

  false
end

Make Status (no instance) respond true to type.match?(value:), then could be simplified to:

def type_matches_value?(type:, value:, proxy:)
  if Low::TypeQuery.complex_type?(expression: type)
    return type.match?(value:)
  elsif type.instance_of?(Class)
    return type == value.class
  elsif type.instance_of?(::Low::TypeExpression)
    type.validate!(value:, proxy:)
    return true
  end

  false
end

F

Use type.display as mentioned in B.

[Piyush-Goenka]

Thanks a lot @maedi for your feedback.

1. Type checking is recursive (I think), so hopefully this just works out of the box. Just write a test first and see if it passes

I tested existing nested expressions like Array[Array[String | Integer]] and confirmed the recursion path is already working for current types.

For Array[Boolean] and Array[Enum[:draft, :published]] specifically — these can only be tested after Boolean and Enum are implemented. My plan is to write those tests as part of the implementation and see if they pass out of the box, as you suggested. If they don't, I'll investigate what additional wiring is needed at that point.

2. Yes, you are very correct in the view of my approach of overriding the inspect but we can make a display function for the same functionality so that no issue arises by the debugger. I have made the changes in the proposal.

3. You're right on all counts.
   I've updated the proposal to introduce a generalised typed_definition? method in TypeQuery instead of the Enum-specific is_a? check. This also fixes the existing gap where Status[200] wasn't being recognised as a complex type since COMPLEX_TYPES.include? matches the class but not the definition object returned by [].

4. Agreed on simplifying type_matches_value?. The updated proposal uses your cleaner version where complex_type? is checked first, before the plain class check. This removes the need for respond_to?(:match?) entirely — instead, implementing match? becomes a contract that every complex type must satisfy. I've also noted that Status would need a class-level match? added to meet that contract consistently.

Thanks a lot for giving your time.
I have learnt why type_definition? is more reliable rather than my hardcoded approach.
I have updated the technical approach as per your views if there is anything more that is required Could you please let me know ?

[Piyush-Goenka]

@maedi
I have updated my technical approach and my timeline of approaching this project.
Could you please give it a look and give your feedback whenever you get time ?

[maedi]

Looks good!

[Piyush-Goenka]

Thanks a lot.