assistant 1.0.0.rc1 → 1.0.0

data/docs/examples/execute-callbacks.md

@@ -1,17 +1,53 @@
----
-title: Execute callbacks
-parent: Examples
-nav_order: 5
----
-
 # Execute callbacks
 
-> **Status:** placeholder — ships in
-> [P10](https://github.com/ramongr/assistant/blob/main/docs/v1/08-github-pages.md#p6p12-examples-one-pr-per-example) of
-> the GitHub Pages plan.
+`before_execute` / `after_execute` / `around_execute` fire around the
+`#execute` body — see the [Composing services guide](../guides/composing-services.md#execute-callbacks)
+for the full contract.
+
+An audit logger and a wall-time wrapper, combined:
+
+```ruby
+class AuditedService < Assistant::Service
+  input :user_id, type: Integer, required: true
+
+  before_execute do
+    log_item_info(source: :audit, detail: :start, message: "user=#{user_id}")
+  end
+
+  after_execute do |_result|
+    log_item_info(source: :audit, detail: :finish, message: "user=#{user_id}")
+  end
+
+  around_execute do |&blk|
+    started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    inner = blk.call
+    elapsed_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round(1)
+    log_item_info(source: :audit, detail: :timing, message: "#{elapsed_ms}ms")
+    inner
+  end
+
+  def execute
+    # ... business logic ...
+  end
+end
+```
+
+Failure semantics:
 
-`before_execute` audit logger plus an `around_execute` timing wrapper, including failure cases.
+* `before_execute` callbacks run **before** `#execute`. Logging an
+  error from a `before_execute` does **not** prevent `#execute` from
+  running — it just becomes part of the result hash. Use the
+  declarative `valid_*_*?` family or `#validate` when you need to
+  short-circuit.
+* `around_execute` blocks receive the inner continuation as the block
+  argument (`&blk`) and **must** call it exactly once. Skipping
+  `blk.call` silently drops the inner result.
+* `after_execute` blocks receive the `#execute` return value as their
+  single positional arg.
+* If a hook itself raises, `Assistant::Service` rescues the
+  `StandardError` and logs it as
+  `source: :hook, detail: :before_execute|:around_execute|:after_execute`
+  — execution of subsequent hooks continues.
 
-When the runnable script under `examples/execute_callbacks/` lands, this
-page will include it verbatim via Jekyll `include_relative` so the
-prose stays in lockstep with the code.
+> Source: [`examples/execute_callbacks/`](https://github.com/ramongr/assistant/tree/main/examples/execute_callbacks) ·
+> Test: [`test/examples/execute_callbacks_example_test.rb`](https://github.com/ramongr/assistant/blob/main/test/examples/execute_callbacks_example_test.rb)

data/docs/examples/instrumentation-notifier.md

@@ -1,17 +1,52 @@
----
-title: Instrumentation notifier
-parent: Examples
-nav_order: 6
----
-
 # Instrumentation notifier
 
-> **Status:** placeholder — ships in
-> [P11](https://github.com/ramongr/assistant/blob/main/docs/v1/08-github-pages.md#p6p12-examples-one-pr-per-example) of
-> the GitHub Pages plan.
+`Assistant.notifier=` accepts any object responding to `#call(event,
+payload)`. Set it once at boot to wire every service into your
+existing instrumentation pipeline — see the [Composing services
+guide](../guides/composing-services.md#instrumentation-notifier)
+for the contract and the
+[API reference](../api-reference.md#instrumentation-notifier) for the
+event list.
+
+Wiring it to an `ActiveSupport::Notifications`-shaped sink:
+
+```ruby
+Assistant.notifier = ->(event, payload) {
+  ActiveSupport::Notifications.instrument("assistant.#{event}", payload)
+}
+```
+
+A fake sink for tests:
+
+```ruby
+events = []
+Assistant.notifier = ->(event, payload) { events << [event, payload] }
+
+CreateUser.run(email: 'a@b.com', name: 'Alice')
+
+events.map(&:first)
+# => [:service_started, :service_validated, :service_executed]
+```
+
+A failure path emits `:service_failed` instead of `:service_executed`:
+
+```ruby
+events.clear
+CreateUser.run(email: nil, name: 'Alice')
+
+events.map(&:first)
+# => [:service_started, :service_validated, :service_failed]
+```
+
+Payload shape for every event is exactly two keys: `service_class:`
+(the `Assistant::Service` subclass) and `duration_s:` (a `Float`
+seconds since `#run` started). The event set and its payload contract
+are **Frozen** for 1.0 — see the
+[full payload table](../api-reference.md#instrumentation-notifier).
 
-`Assistant.notifier=` wired to a fake `ActiveSupport::Notifications`-shaped sink.
+> **Warning** — Notifier callables are rescued from `StandardError`;
+> any exception they raise is `warn`-ed but doesn't fail the service.
+> Don't put control flow in the notifier.
 
-When the runnable script under `examples/instrumentation_notifier/` lands, this
-page will include it verbatim via Jekyll `include_relative` so the
-prose stays in lockstep with the code.
+> Source: [`examples/instrumentation_notifier/`](https://github.com/ramongr/assistant/tree/main/examples/instrumentation_notifier) ·
+> Test: [`test/examples/instrumentation_notifier_example_test.rb`](https://github.com/ramongr/assistant/blob/main/test/examples/instrumentation_notifier_example_test.rb)

data/docs/examples/rails-service.md

@@ -1,17 +1,44 @@
----
-title: Rails service
-parent: Examples
-nav_order: 1
----
-
 # Rails service
 
-> **Status:** placeholder — ships in
-> [P6](https://github.com/ramongr/assistant/blob/main/docs/v1/08-github-pages.md#p6p12-examples-one-pr-per-example) of
-> the GitHub Pages plan.
+A Rails-shaped controller that calls a service and pattern-matches on
+the result hash:
+
+```ruby
+class UsersController < ApplicationController
+  def create
+    case CreateUser.run(**user_params.to_h.symbolize_keys)
+    in { result: user, status: :ok }
+      render json: user, status: :created
+    in { result: user, status: :with_warnings, warnings: }
+      Rails.logger.warn(warnings.map(&:item))
+      render json: user, status: :created
+    in { errors:, status: :with_errors }
+      render json: { errors: errors.map(&:item) },
+             status: :unprocessable_entity
+    end
+  end
+
+  private
+
+  def user_params
+    params.require(:user).permit(:email, :name)
+  end
+end
+```
+
+Notes:
+
+* `Service.run` never raises for application-level failures — it always
+  returns a hash. Use `rescue` only for true exceptions (network,
+  database, etc.), and let `:with_errors` carry the validation /
+  business-rule failures.
+* `LogItem#item` returns a `Hash{Symbol => Object}` that's safe to
+  pass straight to `render json:`.
 
-A Rails-shaped controller calling a service and pattern-matching on the result hash.
+See the [Getting started guide](../getting-started.md) for the
+result-shape contract and the
+[API reference](../api-reference.md#result-shape) for the full status
+enum.
 
-When the runnable script under `examples/rails_service/` lands, this
-page will include it verbatim via Jekyll `include_relative` so the
-prose stays in lockstep with the code.
+> Source: [`examples/rails_service/`](https://github.com/ramongr/assistant/tree/main/examples/rails_service) ·
+> Test: [`test/examples/rails_service_example_test.rb`](https://github.com/ramongr/assistant/blob/main/test/examples/rails_service_example_test.rb)

data/docs/examples/rbs-generator.md

@@ -1,17 +1,94 @@
----
-title: RBS generator
-parent: Examples
-nav_order: 7
----
-
 # RBS generator
 
-> **Status:** placeholder — ships in
-> [P12](https://github.com/ramongr/assistant/blob/main/docs/v1/08-github-pages.md#p6p12-examples-one-pr-per-example) of
-> the GitHub Pages plan.
+`bin/assistant-rbs` (installed as the `assistant-rbs` executable when
+the gem is added to a `Gemfile`) scans Ruby files for
+`Assistant::Service` subclasses and emits per-class RBS sidecar
+signatures into a target directory. See the
+[RBS and types guide](../guides/rbs-and-types.md) for the design
+rationale and Steep setup details.
+
+Given a service like:
+
+```ruby
+# examples/rbs_generator/create_user.rb
+module RbsGeneratorExample
+  class CreateUser < Assistant::Service
+    input :email, type: String, required: true
+    input :name, type: String, required: true
+    input :role, type: [String, Symbol], allow_nil: true, default: nil
+
+    def validate
+      return if email.include?('@')
+
+      log_item_error(source: :validate, detail: :email, message: 'must contain @')
+    end
+
+    def execute
+      { email:, name:, role: role || :member }
+    end
+  end
+end
+```
+
+Run the generator against that file:
+
+```text
+$ bundle exec exe/assistant-rbs examples/rbs_generator/create_user.rb \
+    --output examples/rbs_generator/sig
+```
+
+The committed output lives at
+`examples/rbs_generator/sig/rbs_generator_example/create_user.rbs`:
+
+```rbs
+# Generated by assistant-rbs; do not edit.
+
+module RbsGeneratorExample
+  class CreateUser < Assistant::Service
+
+    def email: () -> String
+    def email?: () -> bool
+    def name: () -> String
+    def name?: () -> bool
+    def role: () -> (String | Symbol)?
+    def role?: () -> bool
+
+  end
+end
+```
+
+Steep can now type-check call sites that read
+`RbsGeneratorExample::CreateUser#email`, `#name`, and `#role`, even though
+those methods are defined via `define_method` at class-load time:
+
+```ruby
+# examples/rbs_generator/type_probe.rb
+service = RbsGeneratorExample::CreateUser.new(email: 'ada@example.com', name: 'Ada', role: :admin)
+
+service.email.upcase
+service.name.length
+service.role&.to_s
+```
+
+Run the example-local check with:
+
+```sh
+cd examples/rbs_generator
+bundle exec steep check --steepfile Steepfile --jobs=1
+```
+
+Notes:
 
-Service definition → `bin/assistant-rbs --output sig` → Steep proving the per-input return type.
+* `--output sig` writes alongside any existing `sig/` tree; the
+  generator only owns files it tagged with its `# Generated by
+  assistant-rbs; do not edit.` marker — hand-written sidecars are left
+  untouched.
+* Re-run after each `Service.input` change. The output is fully
+  derived from the live constant graph, so CI can compare generated
+  output against committed sidecars to catch drift.
+* The generator declares input getters and presence predicates only.
+  Hand-write additional signatures for your own domain methods if your
+  call sites need them.
 
-When the runnable script under `examples/rbs_generator/` lands, this
-page will include it verbatim via Jekyll `include_relative` so the
-prose stays in lockstep with the code.
+> Source: [`examples/rbs_generator/`](https://github.com/ramongr/assistant/tree/main/examples/rbs_generator) ·
+> Test: [`test/examples/rbs_generator_example_test.rb`](https://github.com/ramongr/assistant/blob/main/test/examples/rbs_generator_example_test.rb)

data/docs/examples/sidekiq-worker.md

@@ -1,17 +1,37 @@
----
-title: Sidekiq worker
-parent: Examples
-nav_order: 3
----
-
 # Sidekiq worker
 
-> **Status:** placeholder — ships in
-> [P8](https://github.com/ramongr/assistant/blob/main/docs/v1/08-github-pages.md#p6p12-examples-one-pr-per-example) of
-> the GitHub Pages plan.
+A Sidekiq worker that runs a service idempotently and routes warnings
+and errors to separate sinks:
+
+```ruby
+class CreateUserWorker
+  include Sidekiq::Worker
+  sidekiq_options retry: 5, queue: :default
+
+  def perform(user_attrs)
+    case CreateUser.run(**user_attrs.transform_keys(&:to_sym))
+    in { result:, status: :ok }
+      # Done. Sidekiq sees no exception, no retry.
+    in { result:, status: :with_warnings, warnings: }
+      WarningsSink.publish(worker: self.class.name, items: warnings.map(&:item))
+    in { errors:, status: :with_errors }
+      # Permanent business-rule failure: don't retry, surface to ops.
+      ErrorsSink.publish(worker: self.class.name, items: errors.map(&:item))
+    end
+  end
+end
+```
+
+Notes:
 
-A background job that runs a service idempotently, logging warnings vs errors separately.
+* The worker **never re-raises** for `:with_errors`. Validation /
+  business-rule failures are not transient and shouldn't burn Sidekiq
+  retries. Let true exceptions (network, database) propagate.
+* `LogItem#item` returns plain symbols/strings, which serialize
+  cleanly to JSON / your APM tool.
+* For idempotency, keep `CreateUser` purely declarative: read the
+  caller's identifier, look up existing state, no-op when already
+  satisfied.
 
-When the runnable script under `examples/sidekiq_worker/` lands, this
-page will include it verbatim via Jekyll `include_relative` so the
-prose stays in lockstep with the code.
+> Source: [`examples/sidekiq_worker/`](https://github.com/ramongr/assistant/tree/main/examples/sidekiq_worker) ·
+> Test: [`test/examples/sidekiq_worker_example_test.rb`](https://github.com/ramongr/assistant/blob/main/test/examples/sidekiq_worker_example_test.rb)

data/docs/getting-started.md

@@ -1,8 +1,3 @@
----
-title: Getting started
-nav_order: 1
----
-
 <!-- markdownlint-disable MD013 MD024 -->
 # Getting started
 
@@ -120,6 +115,17 @@ The `:status` value is exhaustively one of `:ok`, `:with_warnings`,
 `:with_errors`. No new status values can be introduced in 1.x without a
 deprecation cycle.
 
+At a glance, that decision is just:
+
+```mermaid
+flowchart LR
+    Run([Service.run]) --> Errors{errors logged?}
+    Errors -- Yes --> WithErrors[":with_errors<br/>(result is nil)"]
+    Errors -- No --> Warnings{warnings logged?}
+    Warnings -- Yes --> WithWarnings[":with_warnings<br/>(result is set)"]
+    Warnings -- No --> Ok[":ok<br/>(result is set)"]
+```
+
 ## What's next
 
 - The same example, but with optional / multi-type inputs and a

data/docs/guides/{index.md → README.md}

@@ -1,10 +1,3 @@
----
-title: Guides
-nav_order: 2
-has_children: true
-permalink: /guides/
----
-
 # Guides
 
 Topic-focused walkthroughs of every part of the Assistant DSL.
@@ -16,7 +9,7 @@ tests under `test/docs/<guide>_examples_test.rb`, and ends with a
   `default:`, `allow_nil:`, `optional:`, `if:` conditional requirement,
   and the `assistant-rbs` Steep recipe.
 - [Validation](./validation.md) — auto-checks, `#validate`, warnings
-  vs errors, conditional requirements, strict `LogItem.new` (M10).
+  vs errors, conditional requirements, strict `LogItem.new`.
 - [Logging and results](./logging-and-results.md) — `LogItem`,
   levels, `log_item_*` shorthands, `merge_logs`, the result hash.
 - [Composing services](./composing-services.md) — `call_service`,

data/docs/guides/composing-services.md

@@ -1,9 +1,3 @@
----
-title: Composing services
-parent: Guides
-nav_order: 4
----
-
 <!-- markdownlint-disable MD013 MD024 -->
 # Composing services
 
@@ -17,8 +11,8 @@ nav_order: 4
 > collaborator.
 
 This guide covers the four composition surfaces shipped in 1.0:
-service-to-service calls (M-S2), execute callbacks (M-S1), the
-instrumentation notifier (M-S3), and the input snapshot (M-S4).
+service-to-service calls, execute callbacks, the instrumentation
+notifier, and the input snapshot.
 
 ## `#call_service`: nest one service inside another
 
@@ -67,7 +61,7 @@ Notes:
 - `call_service` always calls `inner.run`, so calling it twice would
   re-execute the inner service.
 
-## Execute callbacks (M-S1)
+## Execute callbacks
 
 Three class-level DSL methods register callbacks around `#execute`.
 Hooks are evaluated in the context of the service instance.
@@ -112,7 +106,7 @@ Behavior:
 - **Missing block:** registering a hook without a block raises
   `ArgumentError` at class-definition time.
 
-## Instrumentation notifier (M-S3)
+## Instrumentation notifier
 
 Assign a callable to `Assistant.notifier =` to receive a fixed set
 of events for **every** service execution:
@@ -153,7 +147,7 @@ To disable instrumentation entirely, restore the default no-op:
 Assistant.notifier = Assistant::DEFAULT_NOTIFIER
 ```
 
-## `#input_snapshot` (M-S4)
+## `#input_snapshot`
 
 `#input_snapshot` returns a read-only `Data` view of the service's
 declared inputs (post-`default:` / post-`allow_nil:`). It's the
@@ -218,5 +212,5 @@ Notes:
   requirements.
 - [Logging and results](./logging-and-results.md) — what
   `merge_logs(logs:)` does, the result hash shape.
-- [API reference](../api-reference.md#assistantservice) for the
+- [API reference](../api-reference.md#assistant-service) for the
   full callback / call_service / notifier surfaces.

data/docs/guides/inputs.md

@@ -1,9 +1,3 @@
----
-title: Inputs
-parent: Guides
-nav_order: 1
----
-
 <!-- markdownlint-disable MD013 MD024 -->
 # Inputs
 
@@ -40,7 +34,7 @@ Three things to notice:
 1. **`input` and `inputs` take a leading positional name** (`:email`,
    `%i[street city]`). Every other DSL option is a keyword argument.
    This is the only place in the gem where a positional argument
-   survives the M12 keyword-only sweep — see
+   survives the keyword-only DSL — see
    [`api-reference.md`](../api-reference.md#class-methods).
 2. **The constructor is keyword-only.** You call
    `CreateUser.run(email: 'a@b.com', name: 'Alice')`, never
@@ -78,7 +72,7 @@ TouchEmail.run(email: 42)
 #                       message: "Service argument with name email is not a String but Integer">] }
 ```
 
-### Multi-type inputs (M3)
+### Multi-type inputs
 
 Pass an array of classes when more than one is acceptable:
 
@@ -126,7 +120,7 @@ The deprecated 0.x name `#valid_require_<name>?` still works in 1.x —
 calls emit a one-time `Kernel.warn` per call site and delegate to the
 canonical predicate. See [`docs/deprecations.md`](../deprecations.md).
 
-## `default:` (M1)
+## `default:`
 
 Provide a fallback when the caller omits an input. Pass a callable
 (method, lambda, or proc) to compute the default lazily — `assistant`
@@ -155,7 +149,7 @@ input :token, type: String, default: -> { SecureRandom.uuid }
 A `default:` provider that takes arguments raises `ArgumentError` at
 class-definition time.
 
-## `allow_nil:` (M2)
+## `allow_nil:`
 
 By default, `nil` for a typed input logs a type-mismatch error.
 `allow_nil: true` makes `nil` a legal value:
@@ -177,7 +171,7 @@ TouchAge.run(age: 30).fetch(:result)   # => 30
 Combine with `default:` to express "optional integer that defaults to
 nil and may be set to nil explicitly".
 
-## `optional: true` (M7)
+## `optional: true`
 
 `optional: true` is a shorthand for "skip the presence check entirely;
 do not generate `#valid_required_name?`". It is mutually exclusive
@@ -278,7 +272,7 @@ generic `.rbs` for `Service` can't know that your `CreateUser#email`
 returns `String`. That's R1 in
 [`docs/v1/05-quality-and-tooling.md`](https://github.com/ramongr/assistant/blob/main/docs/v1/05-quality-and-tooling.md).
 
-The bundled `assistant-rbs` CLI (M11) closes the gap by emitting
+The bundled `assistant-rbs` CLI closes the gap by emitting
 per-class `.rbs` files. Run it once after editing your services:
 
 ```sh

data/docs/guides/logging-and-results.md

@@ -1,9 +1,3 @@
----
-title: Logging and results
-parent: Guides
-nav_order: 3
----
-
 <!-- markdownlint-disable MD013 MD024 -->
 # Logging and results
 
@@ -12,7 +6,7 @@ nav_order: 3
 > add entries, `#logs` / `#infos` / `#warnings` / `#errors` to read
 > them, and the result hash returned by `.run` to consume the
 > service from outside. `LogItem.new` raises `ArgumentError` for
-> invalid attributes (M10) — prefer the helpers.
+> invalid attributes — prefer the helpers.
 
 This guide covers the data model, the writer helpers, the reader
 predicates, and the shape of the result hash. See the
@@ -32,7 +26,7 @@ fields:
 | `message`  | `String`                       | Human-readable text.                                           |
 | `trace`    | `Array<String>` or `nil`       | Optional backtrace captured at construction.                   |
 
-Constraints (enforced strictly in 1.0 — M10):
+Constraints (enforced strictly in 1.0):
 
 - `source != detail`.
 - `source` and `detail` must each be non-empty.
@@ -46,7 +40,7 @@ Assistant::LogItem::VALID_LEVELS
 
 ## Writing log entries
 
-The three shorthand helpers (M5) are the recommended call sites
+The three shorthand helpers are the recommended call sites
 inside `#validate` and `#execute`:
 
 ```ruby
@@ -162,7 +156,7 @@ def execute
 end
 ```
 
-> **M12.** `#merge_logs` is keyword-only in 1.0. Passing positional
+> **Keyword-only.** `#merge_logs` is keyword-only in 1.0. Passing positional
 > arguments raises `ArgumentError`. The
 > [migration guide](https://github.com/ramongr/assistant/blob/main/docs/v1/06-migration-0x-to-1.md) covers the
 > mechanical rewrite.
@@ -181,14 +175,14 @@ service.errors.first.item
 ## Common pitfalls
 
 - **Pushing onto `@logs` directly.** Don't — always go through the
-  helpers so the M10 strict construction runs and so future
+  helpers so the strict construction runs and so future
   middleware (e.g. an instrumentation hook around `#add_log`) can
   see the entry.
 - **Using `LogItem.new` with `source == detail`.** Raises
   `ArgumentError`. Pick distinct symbols.
 - **Treating `#infos` as part of the contract.** They're for
   introspection only; the result hash never includes them.
-- **Calling `merge_logs(other.logs)` (positional).** M12 requires
+- **Calling `merge_logs(other.logs)` (positional).** 1.0 requires
   the keyword form: `merge_logs(logs: other.logs)`.
 
 ## See also
@@ -197,6 +191,6 @@ service.errors.first.item
   conditional checks, `#validate` mechanics.
 - [Composing services](./composing-services.md) — how `#call_service`
   merges inner logs into the outer timeline.
-- [API reference: LogItem](../api-reference.md#assistantlogitem).
-- [API reference: LogList](../api-reference.md#assistantloglist).
-- [Migration guide](https://github.com/ramongr/assistant/blob/main/docs/v1/06-migration-0x-to-1.md) for M10 + M12.
+- [API reference: LogItem](../api-reference.md#assistant-logitem).
+- [API reference: LogList](../api-reference.md#assistant-loglist).
+- [Migration guide](https://github.com/ramongr/assistant/blob/main/docs/v1/06-migration-0x-to-1.md) for the 1.0 breaking changes.