assistant 0.1.0 → 1.0.0.rc1

data/docs/guides/validation.md

@@ -0,0 +1,180 @@
+---
+title: Validation
+parent: Guides
+nav_order: 2
+---
+
+<!-- markdownlint-disable MD013 MD024 -->
+# Validation
+
+> **TL;DR** — Declarative `input` checks (`type:`, `required:`,
+> `if:`, etc.) run automatically before `#execute`. For everything
+> else, override `#validate` and call `log_item_error(...)` to
+> short-circuit, or `log_item_warning(...)` to flag a recoverable
+> issue. `LogItem.new` raises `ArgumentError` for invalid attributes
+> in 1.0 — use the helpers, not `LogItem.new` directly.
+
+This guide covers the validation surface beyond the declarative
+options on [`input`](./inputs.md): the `validate` hook, the
+warning-vs-error decision, the strict `LogItem` constructor, and
+conditional patterns.
+
+## What runs automatically
+
+For every `Service.input :name, type: T, required: ..., if: ...`,
+the gem generates and runs:
+
+- `#valid_type_name?` — type check (or multi-type with M3 union).
+- `#valid_required_name?` — presence check, when `required: true`.
+- `#valid_required_conditional_name?` — presence + predicate, when
+  `required: true` *and* `if:` are both supplied.
+
+`#run` calls every `valid_required_*?`, `valid_required_conditional_*?`,
+and `valid_type_*?` method that matches by naming convention before
+calling your `#validate`. Failures are logged as error-level
+`LogItem`s and short-circuit `#execute`.
+
+## Adding your own checks with `#validate`
+
+Override `#validate` to log domain-specific errors:
+
+```ruby
+class CreateUser < Assistant::Service
+  input :email, type: String, required: true
+
+  def validate
+    return if email.include?('@')
+
+    log_item_error(source: :validate, detail: :email, message: 'must contain @')
+  end
+
+  def execute
+    { email: }
+  end
+end
+
+CreateUser.run(email: 'a@b.com').fetch(:status) # => :ok
+CreateUser.run(email: 'oops').fetch(:status)    # => :with_errors
+```
+
+`#validate` runs **after** the declarative checks. If a declarative
+check already added an error, your `#validate` still runs (it has the
+chance to surface additional context), but `#execute` is skipped.
+
+## Warning vs. error: how to choose
+
+| Level     | Helper                  | Effect                                                                          |
+|-----------|-------------------------|---------------------------------------------------------------------------------|
+| `:info`   | `log_item_info(...)`    | Recorded on `#logs`; does not affect `#status`.                                 |
+| `:warning`| `log_item_warning(...)` | Flips `#status` from `:ok` to `:with_warnings`; `#execute` still runs.          |
+| `:error`  | `log_item_error(...)`   | Flips `#status` to `:with_errors`; `#execute` is **skipped**, `#result` is nil. |
+
+Rule of thumb:
+
+- **Use an error** when continuing would produce an invalid or
+  misleading result (`#execute` would have to handle the bad state).
+- **Use a warning** when the result is still meaningful but the
+  caller should know something is off (a missing optional input, an
+  in-progress migration shape, a deprecated value).
+
+A worked example:
+
+```ruby
+class CreateUser < Assistant::Service
+  input :email, type: String,  required: true
+  input :age,   type: Integer, allow_nil: true, default: nil
+
+  def validate
+    log_item_error(source: :validate, detail: :email, message: 'invalid email') unless email.include?('@')
+    log_item_warning(source: :validate, detail: :age, message: 'age missing') if age.nil?
+  end
+
+  def execute
+    { email:, age: }
+  end
+end
+
+CreateUser.run(email: 'a@b.com').fetch(:status)
+# => :with_warnings — age is missing, but we still build the result
+
+CreateUser.run(email: 'oops').fetch(:status)
+# => :with_errors — execute is skipped
+```
+
+## Conditional requirements
+
+When a presence check should fire only sometimes, combine
+`required: true` with `if:`:
+
+```ruby
+class UpdateUser < Assistant::Service
+  input :role,   type: Symbol, default: :member
+  input :reason, type: String, required: true, if: ->(_value) { true }
+
+  def execute
+    { role:, reason: }
+  end
+end
+
+UpdateUser.run(role: :member).fetch(:status)
+# => :with_errors — predicate is truthy, so :reason is required
+
+UpdateUser.run(role: :member, reason: 'audit cleanup').fetch(:status)
+# => :ok
+```
+
+The `if:` predicate is called with the *input's own value*. The
+validator requires the input to be present **and** the predicate to
+be truthy — so the canonical use is "I need this to be present
+*when* some other condition holds". See
+[`inputs.md`](./inputs.md#if-conditional-requirement) for the
+inverse pattern.
+
+## `LogItem.new` raises in 1.0 (M10)
+
+Constructing a `LogItem` directly with invalid attributes now raises
+`ArgumentError`. The `#valid?` family is kept for introspection but
+always returns `true` after a successful `new`:
+
+```ruby
+Assistant::LogItem.new(level: :info, source: :a, detail: :b, message: 'ok').valid?
+# => true
+
+begin
+  Assistant::LogItem.new(level: :info, source: :a, detail: :b, message: '')
+rescue ArgumentError => e
+  e.message # => "invalid LogItem: message must be present"
+end
+```
+
+Inside a `Service`, you almost never need `LogItem.new` directly:
+`log_item_info(...)`, `log_item_warning(...)`, `log_item_error(...)`,
+and `add_log(level:, source:, detail:, message:)` build the item and
+append it to `#logs` for you. See
+[`logging-and-results.md`](./logging-and-results.md) for the full
+catalogue.
+
+## Common pitfalls
+
+- **Returning `false` from `#validate` to signal failure.** The hook's
+  return value is ignored. The only way to fail is to log an
+  error-level `LogItem`.
+- **Calling `raise` inside `#validate` or `#execute`.** Don't —
+  `assistant` is soft-fail. Convert expected failures into log items.
+  Unexpected exceptions propagate (the gem catches exceptions only
+  in `before_execute` / `around_execute` / `after_execute` hooks).
+- **Building `LogItem.new(...)` and pushing it onto `#logs`.** Use the
+  helpers; they apply the same M10 strict construction and keep your
+  call sites readable.
+- **Forgetting that `#validate` runs even when a declarative check
+  already failed.** Either guard `#validate` with `return if
+  errors.any?`, or design it to add complementary errors.
+
+## See also
+
+- [Inputs guide](./inputs.md) — `required:`, `if:`, multi-type, the
+  generated `valid_*` predicates.
+- [Logging and results](./logging-and-results.md) — the helpers, the
+  full result hash, log filtering.
+- [API reference: LogItem](../api-reference.md#assistantlogitem).
+- [API reference: LogList](../api-reference.md#assistantloglist).

data/docs/index.md

@@ -0,0 +1,69 @@
+---
+title: Home
+layout: home
+nav_order: 0
+permalink: /
+---
+
+# Assistant
+
+**Tiny, dependency-free soft-fail service objects for Ruby.**
+
+[![Gem Version](https://badge.fury.io/rb/assistant.svg)](https://rubygems.org/gems/assistant)
+[![CI](https://github.com/ramongr/assistant/actions/workflows/ci.yml/badge.svg)](https://github.com/ramongr/assistant/actions/workflows/ci.yml)
+
+Assistant lets you write service objects that **never raise for expected
+failures**. A service declares its inputs, validates them, runs its body, and
+returns a uniform result hash that always carries either a value plus
+warnings or a list of errors. Ships with RBS signatures, a 1.0-frozen public
+API, and zero runtime gem dependencies.
+
+## Install
+
+```ruby
+# Gemfile
+gem 'assistant', '~> 1.0'
+```
+
+```sh
+bundle install
+```
+
+Ruby 3.4 or newer is required.
+
+## The 60-second example
+
+```ruby
+require 'assistant'
+
+class CreateUser < Assistant::Service
+  input :email, type: String, required: true
+  input :name,  type: String, default: 'Anonymous'
+
+  def execute
+    log_item_info(source: :create_user, detail: :persisted, message: "saved #{email}")
+    User.create!(email: email, name: name)
+  end
+end
+
+case CreateUser.run(email: 'me@example.com')
+in { result:, status: :ok }
+  result
+in { errors:, status: :with_errors }
+  errors.map(&:item)
+end
+```
+
+## Where to next
+
+- **[Getting started](getting-started.md)** — walk through your first
+  service end-to-end.
+- **[Guides](guides/inputs.md)** — DSL deep-dives, one page per concern.
+- **[API reference](api-reference.md)** — every Frozen symbol, deep-link
+  friendly.
+- **[Examples](examples/index.md)** — runnable patterns (Rails, CLI,
+  Sidekiq, composition, callbacks, instrumentation, RBS).
+- **[Roadmap](roadmap.md)** — what's planned, what shipped.
+- **[Changelog](changelog.md)** — full release history.
+
+Source on [GitHub](https://github.com/ramongr/assistant).

data/docs/roadmap.md

@@ -0,0 +1,33 @@
+---
+title: Roadmap
+nav_order: 6
+---
+
+# Roadmap
+
+The full 1.0 plan lives in
+[`docs/v1/`](https://github.com/ramongr/assistant/tree/main/docs/v1) in
+the repository. Each file below is a focused planning document; the
+index ties them together.
+
+| Doc | What it covers |
+| --- | --- |
+| [`README.md`](https://github.com/ramongr/assistant/blob/main/docs/v1/README.md) | Plan index and reading order. |
+| [`00-overview.md`](https://github.com/ramongr/assistant/blob/main/docs/v1/00-overview.md) | 1.0 goals, non-goals, acceptance criteria. |
+| [`01-api-surface.md`](https://github.com/ramongr/assistant/blob/main/docs/v1/01-api-surface.md) | Frozen vs Experimental symbols, stability labels. |
+| [`02-features.md`](https://github.com/ramongr/assistant/blob/main/docs/v1/02-features.md) | M1–M13 milestones and the promoted M-S* set. |
+| [`03-documentation.md`](https://github.com/ramongr/assistant/blob/main/docs/v1/03-documentation.md) | D1–D5 documentation deliverables. |
+| [`04-release-checklist.md`](https://github.com/ramongr/assistant/blob/main/docs/v1/04-release-checklist.md) | Pre-release, RC, release, and post-release steps. |
+| [`05-quality-and-tooling.md`](https://github.com/ramongr/assistant/blob/main/docs/v1/05-quality-and-tooling.md) | SimpleCov, RuboCop, Steep, CI matrix. |
+| [`06-migration-0x-to-1.md`](https://github.com/ramongr/assistant/blob/main/docs/v1/06-migration-0x-to-1.md) | The three mechanical rewrites required to upgrade. |
+| [`07-risks-and-open-questions.md`](https://github.com/ramongr/assistant/blob/main/docs/v1/07-risks-and-open-questions.md) | Known constraints (e.g. R1 RBS limitation) and resolutions. |
+| [`08-github-pages.md`](https://github.com/ramongr/assistant/blob/main/docs/v1/08-github-pages.md) | The plan for **this site** (parallel deliverable, not a 1.0 gate). |
+
+## Current snapshot
+
+- 1.0 release plumbing is in flight — the gem is at
+  [`1.0.0.rc1`](changelog.md) and the migration recipe is finalised.
+- Every "Must" milestone (M1–M13) and every promoted "Should"
+  (M-S1–M-S4) has shipped to `main`.
+- The Jekyll site you're reading now is P2 of the GitHub Pages plan;
+  later phases land the remaining guide / example content.

data/exe/assistant-rbs

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'assistant'
+require 'assistant/rbs_generator'
+
+exit Assistant::RbsGenerator::Cli.run(ARGV)

data/lib/assistant/execute_callbacks.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+# Class-level DSL for registering `before_execute` / `after_execute` /
+# `around_execute` hooks on `Assistant::Service` subclasses (M-S1).
+#
+# Mixed into `Service.singleton_class` so the DSL is available at class
+# definition time. Hooks are stored as `UnboundMethod`s on private
+# anonymous Modules so we can bind `self` to the service instance and
+# still pass a block (the continuation) into `around_execute` hooks.
+#
+# Hooks are inherited at subclass-definition time: a subclass receives
+# a duplicate of each registered hook array. Adding more hooks to the
+# subclass does not affect the parent, and vice-versa.
+#
+# See docs/v1/02-features.md M-S1 and docs/v1/01-api-surface.md.
+module Assistant::ExecuteCallbacks
+  # The exhaustive set of hook types this module manages.
+  # @return [Array<Symbol>]
+  HOOK_TYPES = %i[before_execute after_execute around_execute].freeze
+
+  # @return [Array<UnboundMethod>] hooks registered via {#before_execute}, in declaration order
+  def before_execute_hooks
+    @before_execute_hooks ||= []
+  end
+
+  # @return [Array<UnboundMethod>] hooks registered via {#after_execute}, in declaration order
+  def after_execute_hooks
+    @after_execute_hooks ||= []
+  end
+
+  # @return [Array<UnboundMethod>] hooks registered via {#around_execute}, in declaration order
+  def around_execute_hooks
+    @around_execute_hooks ||= []
+  end
+
+  # Register a block to run after validation and before `#execute`.
+  # `self` inside the block is the service instance.
+  #
+  # @yield runs in the context of the service instance after validation, before `#execute`
+  # @raise [ArgumentError] when no block is given
+  # @return [Array<UnboundMethod>] the updated {#before_execute_hooks} chain
+  def before_execute(&block)
+    raise ArgumentError, 'before_execute requires a block' unless block
+
+    before_execute_hooks << build_hook(block)
+  end
+
+  # Register a block to run after `#execute` returns. `self` inside the
+  # block is the service instance; the execute result is passed as the
+  # single positional argument.
+  #
+  # @yieldparam execute_result [Object] return value of `#execute`
+  # @raise [ArgumentError] when no block is given
+  # @return [Array<UnboundMethod>] the updated {#after_execute_hooks} chain
+  def after_execute(&block)
+    raise ArgumentError, 'after_execute requires a block' unless block
+
+    after_execute_hooks << build_hook(block)
+  end
+
+  # Register a block that wraps `#execute`. `self` inside the block is
+  # the service instance; the `&blk` block argument yields to the
+  # inner stack (the next around hook, or `#execute` for the innermost
+  # layer). Declaration order wraps: the first declared hook is the
+  # outermost layer.
+  #
+  # @yield runs in the context of the service instance, wrapping the inner stack
+  # @yieldparam blk [Proc] the continuation; call `yield` (or `blk.call`) to invoke the inner layer
+  # @raise [ArgumentError] when no block is given
+  # @return [Array<UnboundMethod>] the updated {#around_execute_hooks} chain
+  def around_execute(&block)
+    raise ArgumentError, 'around_execute requires a block' unless block
+
+    around_execute_hooks << build_hook(block)
+  end
+
+  # Snapshot parent hooks into the subclass at definition time. The
+  # snapshot is a `dup` so the subclass owns its own array and further
+  # additions on either side never bleed across the hierarchy.
+  #
+  # @param subclass [Class] freshly defined subclass
+  # @return [void]
+  def inherited(subclass)
+    super
+    subclass.instance_variable_set(:@before_execute_hooks, before_execute_hooks.dup)
+    subclass.instance_variable_set(:@after_execute_hooks,  after_execute_hooks.dup)
+    subclass.instance_variable_set(:@around_execute_hooks, around_execute_hooks.dup)
+  end
+
+  private
+
+  # Wrap the user's block in an anonymous Module so we can convert it
+  # to an `UnboundMethod`. `um.bind_call(service, *args, &cont)` then
+  # runs the user's block with `self` == the service instance AND
+  # passes a block argument through to the block's `&blk` parameter,
+  # which is essential for `around_execute` continuations and cannot
+  # be expressed with `instance_exec` alone.
+  def build_hook(block)
+    mod = Module.new
+    mod.send(:define_method, :__assistant_execute_hook__, &block)
+    mod.instance_method(:__assistant_execute_hook__)
+  end
+end

data/lib/assistant/execute_callbacks.rbs

@@ -0,0 +1,30 @@
+# Type signatures for `lib/assistant/execute_callbacks.rb`. See
+# docs/v1/01-api-surface.md for the frozen 1.0 surface. The block types
+# for `before_execute` / `after_execute` / `around_execute` are loosely
+# typed because the user's block can take a `&blk` continuation, varied
+# `result` shapes, or no arguments at all — RBS cannot model the
+# `instance_exec`-like rebinding precisely.
+
+module Assistant
+  module ExecuteCallbacks
+    HOOK_TYPES: Array[Symbol]
+
+    @before_execute_hooks: Array[UnboundMethod]
+    @after_execute_hooks: Array[UnboundMethod]
+    @around_execute_hooks: Array[UnboundMethod]
+
+    def before_execute_hooks: () -> Array[UnboundMethod]
+    def after_execute_hooks: () -> Array[UnboundMethod]
+    def around_execute_hooks: () -> Array[UnboundMethod]
+
+    def before_execute: () { (*untyped) -> untyped } -> Array[UnboundMethod]
+    def after_execute: () { (*untyped) -> untyped } -> Array[UnboundMethod]
+    def around_execute: () { (*untyped) -> untyped } -> Array[UnboundMethod]
+
+    def inherited: (Class subclass) -> void
+
+    private
+
+    def build_hook: (Proc block) -> UnboundMethod
+  end
+end

data/lib/assistant/input_builder/accessors.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'assistant/refinements/string_blankness'
+
+# Generators for the per-input reader and `?`-checker instance methods.
+# The lexical refinement `Assistant::Refinements::StringBlankness` is
+# activated here only (narrower than the pre-M13 module-wide `using`).
+module Assistant::InputBuilder::Accessors
+  using Assistant::Refinements::StringBlankness
+
+  # Define `#name` reader on the host class. Returns the raw value
+  # stored under `@inputs[name]`.
+  #
+  # @param name [Symbol] input name
+  # @return [void]
+  def input_getter_meth(name:)
+    define_method(name) do
+      @inputs[name]
+    end
+  end
+
+  # Define `#name?` predicate on the host class. Treats `nil`, `false`,
+  # whitespace-only strings, and `#empty?` collections as missing.
+  #
+  # @param name [Symbol] input name
+  # @return [void]
+  def input_checker_meth(name:)
+    define_method("#{name}?") do
+      val = @inputs[name]
+      return false if val.nil? || val == false
+      return !val.whitespace? if val.is_a?(String)
+
+      val.respond_to?(:empty?) ? !val.empty? : true
+    end
+  end
+end

data/lib/assistant/input_builder/accessors.rbs

@@ -0,0 +1,10 @@
+# Type signatures for `lib/assistant/input_builder/accessors.rb`. Each
+# helper defines a per-input instance method on the host Service
+# subclass via `define_method`; from RBS's perspective the helpers
+# return whatever `define_method` returns (a Symbol).
+
+module Assistant::InputBuilder::Accessors
+  def input_getter_meth: (name: Symbol) -> Symbol
+
+  def input_checker_meth: (name: Symbol) -> Symbol
+end

data/lib/assistant/input_builder/default_option.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# M1: class-time gate for the `default:` option — fail fast on illegal
+# providers, warn on shared mutable literals. Pure side-effects, no
+# interaction with the per-class definitions registry.
+module Assistant::InputBuilder::DefaultOption
+  # Run the class-time gate for an input's `default:` provider:
+  # reject illegal providers, warn on shared mutable literals.
+  #
+  # @param name    [Symbol] input name
+  # @param default [Object, Proc] the literal value or zero-arity Proc
+  # @return [void]
+  # @raise [ArgumentError] when `default` is callable but not a zero-arity Proc
+  def process_default_option(name:, default:)
+    validate_default!(name:, default:)
+    warn_on_mutable_default(name:, default:)
+  end
+
+  # M1: a default: provider must be either a literal value or a
+  # zero-arity Proc/Lambda. Anything else that responds to #call (a
+  # Method object, a custom callable) is rejected at class-definition
+  # time.
+  def validate_default!(name:, default:)
+    if default.is_a?(Proc) && !default.arity.zero? && default.arity != -1
+      raise ArgumentError, "default: for input :#{name} must be a zero-arity Proc, got arity #{default.arity}"
+    elsif !default.is_a?(Proc) && default.respond_to?(:call)
+      raise ArgumentError, "default: for input :#{name} must be a literal or a zero-arity Proc, not a #{default.class}"
+    end
+  end
+
+  # M1: warn when a mutable literal default (unfrozen Array/Hash) is
+  # used — such a default is shared across every instance of the
+  # Service subclass and almost never what the author wants. Frozen
+  # literals and Procs are safe and pass silently.
+  def warn_on_mutable_default(name:, default:)
+    return unless (default.is_a?(Array) || default.is_a?(Hash)) && !default.frozen?
+
+    Kernel.warn("assistant: input :#{name} has a mutable #{default.class} default; " \
+                'use `default: -> { ... }` to avoid sharing state across instances')
+  end
+end

data/lib/assistant/input_builder/default_option.rbs

@@ -0,0 +1,11 @@
+# Type signatures for `lib/assistant/input_builder/default_option.rb`
+# (M1). Raises `ArgumentError` at class-definition time for illegal
+# default providers; warns on shared mutable literals.
+
+module Assistant::InputBuilder::DefaultOption
+  def process_default_option: (name: Symbol, default: untyped) -> void
+
+  def validate_default!: (name: Symbol, default: untyped) -> void
+
+  def warn_on_mutable_default: (name: Symbol, default: untyped) -> void
+end

data/lib/assistant/input_builder/dsl.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# Public DSL surface: declarative `#input`/`#inputs` that register an
+# input definition and generate the per-input accessor + validator
+# instance methods on the host Service subclass. Calls into every
+# other InputBuilder submodule.
+#
+# These two methods deliberately keep their leading positional `name`
+# parameter even though every other M12 helper is keyword-only --
+# `input :foo, type: String` reads better as a class-body declaration
+# than `input name: :foo, type: String`. The internal helpers we call
+# below are still keyword-only; we just map the positional `attr_name`
+# /`attr_names` here to `name:` / `names:` on the way down.
+module Assistant::InputBuilder::Dsl
+  # Lists all inputs that have the same type and options.
+  def inputs(attr_names, type:, **)
+    attr_names.each do |attr_name|
+      input(attr_name, type:, **)
+    end
+  end
+
+  # Individual input with a specific type or options.
+  def input(attr_name, type:, **options)
+    process_default_option(name: attr_name, default: options[:default]) if options.key?(:default)
+    options = process_optional_option(name: attr_name, options:) if options.key?(:optional)
+    register_input_definition(name: attr_name, type:, options:)
+
+    # Base Methods
+    input_getter_meth(name: attr_name)
+    input_checker_meth(name: attr_name)
+
+    # Input type validation method, simple and conditional requirement validation methods
+    input_type_validator_meth(name: attr_name, type:, **options)
+    input_require_validator_meth(name: attr_name, **options) if options[:required] == true
+    input_require_conditional_meth(name: attr_name, **options) if options[:required] == true && options[:if]
+  end
+end

data/lib/assistant/input_builder/dsl.rbs

@@ -0,0 +1,12 @@
+# Type signatures for `lib/assistant/input_builder/dsl.rb`. The public
+# `#input`/`#inputs` DSL surface; see docs/v1/01-api-surface.md.
+#
+# Note: `#input` and `#inputs` deliberately keep their leading
+# positional `attr_name`/`attr_names` parameter; every other M12 helper
+# is keyword-only.
+
+module Assistant::InputBuilder::Dsl
+  def inputs: (Array[Symbol] attr_names, type: untyped, **untyped) -> Array[Symbol]
+
+  def input: (Symbol attr_name, type: untyped, **untyped) -> untyped
+end

data/lib/assistant/input_builder/optional_option.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# M7: explicit `optional:` flag handling. Validates the value and
+# returns the canonical option hash (with `:required` derived from
+# `optional: false`). Mirrors `DefaultOption`'s shape so the `#input`
+# call site stays one line per option family.
+module Assistant::InputBuilder::OptionalOption
+  # Validate the `optional:` keyword for an input and return the
+  # canonical option hash. `optional: false` is translated into
+  # `required: true` so downstream validators see a single flag.
+  #
+  # @param name    [Symbol] input name
+  # @param options [Hash]   options hash from the `#input` call
+  # @return [Hash] the (possibly translated) options hash
+  # @raise [ArgumentError] when `optional:` is non-boolean or contradicts `required: true`
+  def process_optional_option(name:, options:)
+    validate_optional!(name:, options:)
+    apply_optional_option(options)
+  end
+
+  # M7: `optional:` must be a boolean. `optional: true` together with
+  # `required: true` is a contradiction. Both rules raise
+  # `ArgumentError` at class-definition time, before any method is
+  # generated.
+  def validate_optional!(name:, options:)
+    optional = options[:optional]
+    unless [true, false].include?(optional)
+      raise ArgumentError, "optional: for input :#{name} must be true or false, got #{optional.inspect}"
+    end
+    return unless optional == true && options[:required] == true
+
+    raise ArgumentError, "input :#{name} cannot be both required: true and optional: true"
+  end
+
+  # M7: pure translation of the validated `optional:` value into the
+  # canonical `required:` flag used by downstream validator helpers.
+  # `optional: false` -> `required: true`; `optional: true` is left
+  # alone (no `valid_require_<name>?` is generated, matching the
+  # default). The original `:optional` key is retained in
+  # `input_definitions` for introspection. Non-mutating: callers
+  # receive a new hash when a translation is applied.
+  def apply_optional_option(options)
+    options[:optional] == false ? options.merge(required: true) : options
+  end
+end

data/lib/assistant/input_builder/optional_option.rbs

@@ -0,0 +1,10 @@
+# Type signatures for `lib/assistant/input_builder/optional_option.rb`
+# (M7). Validates the `optional:` flag and normalises the option hash.
+
+module Assistant::InputBuilder::OptionalOption
+  def process_optional_option: (name: Symbol, options: Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+
+  def validate_optional!: (name: Symbol, options: Hash[Symbol, untyped]) -> void
+
+  def apply_optional_option: (Hash[Symbol, untyped] options) -> Hash[Symbol, untyped]
+end

data/lib/assistant/input_builder/registry.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Per-class registry of input definitions. Each Service subclass gets its
+# own hash keyed by attribute name with the original keyword options
+# frozen for introspection (used by Service#initialize for M1 defaulting
+# and by the M11 RBS generator).
+module Assistant::InputBuilder::Registry
+  # Per-class hash of input definitions, keyed by attribute name.
+  # Values are frozen `{ type:, **options }` hashes. Read by
+  # `Service#initialize` (M1 defaulting), by `Service#input_snapshot`
+  # (M-S4), and by the M11 RBS generator.
+  #
+  # @return [Hash{Symbol => Hash}]
+  def input_definitions
+    @input_definitions ||= {}
+  end
+
+  # Register or replace an input definition.
+  #
+  # @param name    [Symbol] input name
+  # @param type    [Class, Array<Class>] declared type(s)
+  # @param options [Hash]   remaining `#input` keyword options
+  # @return [Hash] the frozen definition entry just stored
+  def register_input_definition(name:, type:, options:)
+    input_definitions[name] = { type:, **options }.freeze
+  end
+end