dami 1.0.0

data/docs/07.Associations.md

@@ -0,0 +1,239 @@
+# Chapter 7: Associations
+
+Associations are powerful shortcuts that link your models together, allowing you to easily query and interact with related records. Instead of writing manual joins and foreign key lookups, you can navigate your data's relationships intuitively.
+
+All associations are **lazy-loaded** by default, meaning the related data is only fetched from the database when you first access it.
+
+## One-to-Many Relationships
+
+This is the most common relationship type, connecting one model to many others.
+
+### `belongs_to`
+
+This association indicates that a model has a foreign key that points to another model. For example, a `Post` belongs to a `User`. This assumes your `posts` table has a `user_id` column.
+
+#### **Definition**
+
+```ruby
+Dami.model :posts do
+  fields { field :user_id, :integer; field :title, :string }
+  relationships do
+    belongs_to :user
+  end
+end
+```
+
+#### **Usage**
+
+When you access the association, Dami automatically runs a query to find the related record.
+
+```ruby
+post = Dami.db(:posts).find(1)
+
+# This triggers a new query: SELECT * FROM users WHERE id = ... LIMIT 1
+author = post.user
+
+puts author[:name] # => "Alice"
+```
+
+✍️
+
+-----
+
+### `has_many`
+
+This is the inverse of `belongs_to`. It indicates that a model can be associated with many instances of another model. A `User` has many `Posts`.
+
+#### **Definition**
+
+```ruby
+Dami.model :users do
+  fields { field :name, :string }
+  relationships do
+    has_many :posts
+  end
+end
+```
+
+#### **Usage**
+
+Accessing a `has_many` association returns a `Query::Builder` instance, allowing you to chain additional queries before fetching the data.
+
+```ruby
+user = Dami.db(:users).find(1)
+
+# This does NOT run a query yet. It returns a query builder.
+user_posts_query = user.posts
+
+# Now you can chain more conditions...
+published_posts = user_posts_query.where(status: 'published').to_a
+
+# Or just get them all. This executes the query.
+all_posts = user.posts.to_a
+puts all_posts.length # => 5
+```
+
+-----
+
+## One-to-One Relationships
+
+### `has_one`
+
+A `has_one` association is a special case where a model is associated with at most one other record. For example, a `User` has one `Profile`. This assumes your `profiles` table has a `user_id` column.
+
+#### **Definition**
+
+```ruby
+Dami.model :users do
+  fields { field :name, :string }
+  relationships do
+    has_one :profile
+  end
+end
+```
+
+#### **Usage**
+
+```ruby
+user = Dami.db(:users).find(1)
+
+# This triggers a query: SELECT * FROM profiles WHERE user_id = ... LIMIT 1
+user_profile = user.profile
+
+puts user_profile[:bio] # => "Loves writing about Dami."
+```
+
+-----
+
+## Eager Loading with `.preload`
+
+Lazy loading is convenient, but it can lead to a major performance issue known as the **N+1 Query Problem**.
+
+⚠️ **The N+1 Problem:** Imagine you fetch 10 posts and then loop through them to print the author's name.
+
+```ruby
+posts = Dami.db(:posts).limit(10).to_a # 1 query
+
+posts.each do |post|
+  puts post.user[:name] # N (10) additional queries! One for each post.
+end
+# Total Queries: 1 + 10 = 11
+```
+
+This is incredibly inefficient. The solution is **eager loading**. Use `.preload` to tell Dami to fetch the associated data in advance using the minimum number of queries.
+
+```ruby
+# This runs only TWO queries, no matter how many posts there are.
+posts = Dami.db(:posts).preload(:user).limit(10).to_a
+# Query 1: SELECT * FROM posts LIMIT 10
+# Query 2: SELECT * FROM users WHERE id IN (1, 2, 5, ...)
+
+posts.each do |post|
+  # No new query is run here! The user data is already loaded.
+  puts post.user[:name]
+end
+# Total Queries: 2
+```
+
+You can preload multiple associations at once:
+`Dami.db(:users).preload(:posts, :profile).to_a`
+
+-----
+
+## Many-to-Many Relationships
+
+### `has_many :through`
+
+This association is used for many-to-many relationships, which require a third "join" table. For example, a `Post` can have many `Tags`, and a `Tag` can be on many `Posts`. The connection is made through a `posts_tags` table.
+
+#### **Definition**
+
+You must define the associations on all three models.
+
+```ruby
+Dami.model :posts do
+  relationships do
+    has_many :posts_tags
+    has_many :tags, through: :posts_tags
+  end
+end
+
+Dami.model :tags do
+  relationships do
+    has_many :posts_tags
+    has_many :posts, through: :posts_tags
+  end
+end
+
+Dami.model :posts_tags do # The join model
+  relationships do
+    belongs_to :post
+    belongs_to :tag
+  end
+end
+```
+
+#### **Usage**
+
+You can now access the association directly, and Dami handles the join automatically.
+
+```ruby
+post = Dami.db(:posts).find(1)
+puts post.tags.map { |t| t[:name] } # => ["ruby", "orm"]
+
+tag = Dami.db(:tags).find(5)
+puts tag.posts.count # => 42
+```
+
+-----
+
+## Polymorphic Associations
+
+A polymorphic association allows a model to belong to more than one type of other model on a single association. A classic example is a `Comment` which can belong to a `Post`, an `Article`, or a `Video`.
+
+This requires two columns on the "belonging" model: `commentable_id` (an integer) and `commentable_type` (a string like "Post" or "Article").
+
+#### **Definition**
+
+```ruby
+# The polymorphic model
+Dami.model :comments do
+  relationships do
+    belongs_to commentable: { polymorphic: true }
+  end
+end
+
+# The models that can be commented on
+Dami.model :posts do
+  relationships do
+    has_many comments: { as: :commentable, model: :comments }
+  end
+end
+
+Dami.model :articles do
+  relationships do
+    has_many comments: { as: :commentable, model: :comments }
+  end
+end
+```
+
+#### **Usage**
+
+Dami automatically figures out which type of record to fetch.
+
+```ruby
+comment = Dami.db(:comments).find(1) # This one is on a Post
+parent = comment.commentable
+puts parent[:title] # => "My Awesome Post"
+
+comment2 = Dami.db(:comments).find(2) # This one is on an Article
+parent2 = comment2.commentable
+puts parent2[:headline] # => "A Great Article"
+```
+
+
+
+## What's Next?
+
+  * **Chapter 8: Scopes** - Create reusable query shortcuts to keep your code clean and readable.
+  * **Chapter 9: Migrations** - Learn how to manage your database schema over time.

data/docs/08.Scopes.md

@@ -0,0 +1,99 @@
+# Chapter 8: Scopes
+
+Scopes are named query shortcuts that let you encapsulate commonly used query logic directly into your model definitions. They allow you to turn complex, repetitive query chains into clean, readable, and reusable methods.
+
+Think of scopes as custom filters for your models. Instead of writing `.where(status: 'active')` everywhere, you can simply call `.active`.
+
+-----
+
+## Defining Scopes
+
+Scopes are defined within a `scopes` block in your model using the `.scope` method. Each scope takes a name and a lambda that returns a `Query::Builder` instance.
+
+```ruby
+Dami.scopes :posts do
+  # A simple scope without arguments
+  scope :published, -> { where(status: 'published') }
+  
+  # A scope that chains other query methods
+  scope :recent, -> { order(created_at: :desc).limit(10) }
+
+end
+```
+
+-----
+
+## Using Scopes
+
+Once defined, a scope can be called just like any other method on your query builder.
+
+```ruby
+# Get all published posts
+published_posts = Dami.db(:posts).published.to_a
+
+# Get the 10 most recent posts
+recent_posts = Dami.db(:posts).recent.to_a
+```
+
+### Chaining Scopes 🔗
+
+The real power of scopes comes from chaining them together. Dami combines them using `AND`, allowing you to compose complex queries from simple, reusable parts.
+
+```ruby
+# Get the 10 most recent PUBLISHED posts
+recent_published = Dami.db(:posts).published.recent.to_a
+```
+
+This is far more readable than chaining the underlying `where`, `order`, and `limit` calls every time.
+
+-----
+
+## Scopes with Arguments
+
+Scopes can also accept arguments, making them even more flexible. The arguments you pass to the scope method will be passed directly to the lambda.
+
+#### **Definition**
+
+```ruby
+Dami.scopes :users do
+
+  # Find users by a specific status
+  scope :by_status, ->(status) { where(status: status) }
+
+  # Find users created after a certain date
+  scope :created_after, ->(date) { where('created_at > ?', date) }
+
+end
+```
+
+#### **Usage**
+
+```ruby
+# Get all pending users
+pending_users = Dami.db(:users).by_status('pending').to_a
+
+# Get users created in the last week and chain it with another scope
+recent_active_users = Dami.db(:users)
+  .active # Assuming an :active scope exists
+  .created_after(1.week.ago)
+  .to_a
+```
+
+-----
+
+## Best Practices & Why Use Scopes?
+
+Scopes are a fundamental tool for writing clean and maintainable data-access code.
+
+  * **DRY (Don't Repeat Yourself)**: Scopes centralize your query logic. If the definition of a "published" post changes (e.g., to `status IN ('live', 'promoted')`), you only need to update the scope in one place, and your entire application will reflect the change.
+
+  * **Readability**: Scopes make your code self-documenting. `Dami.db(:posts).published.recent` is immediately understandable, whereas the underlying chain of `where` and `order` clauses is not.
+
+  * **Composability**: Scopes are like building blocks. You can define small, focused scopes and chain them together to build sophisticated queries without duplicating logic.
+
+-----
+
+## What's Next?
+
+  * **Chapter 9: Migrations** - Learn how to manage your database schema over time with versioned changes.
+  * **Chapter 10: Advanced Topics** - Explore transactions, flows, and other powerful features.

data/docs/09.Migrations.md

@@ -0,0 +1,165 @@
+# Chapter 9: Migrations
+
+Migrations are the definitive history of your database schema, allowing you to evolve its structure in a safe, repeatable, and collaborative way. Dami provides a powerful migrator and an **intelligent migration generator** that automates the most tedious parts of schema management, letting you focus on your models.
+
+-----
+
+## The Magic Workflow: Let Dami Write Your Migrations ✨
+
+With Dami, you rarely need to write migrations by hand. The primary workflow is simple and incredibly fast:
+
+1.  **Modify Your Models**: Make changes directly in your `Dami.model` definitions. Add a field, remove a field, or add a `belongs_to` relationship.
+2.  **Generate the Migration**: Run a single command in your terminal.
+3.  **Review and Migrate**: Inspect the auto-generated migration file, then run it.
+
+#### **Example: Adding an `age` Column to Users**
+
+**Step 1: Edit the Model**
+You decide `users` need an `age` column. You simply add it to the `fields` block.
+
+```ruby
+# app/models/user.rb
+Dami.model :users do
+  fields do
+    field :name, :string
+    field :email, :string
+    field :age, :integer  # <-- You add this line
+  end
+end
+```
+
+**Step 2: Generate the Migration**
+Run the `generate` command from your terminal.
+
+```bash
+dami generate migration AddAgeToUsers
+```
+
+Dami introspects your models, compares them to the last known schema (`db/schema.rb`), and detects that the `age` column is missing. It then writes the perfect migration file for you.
+
+```
+✅ New migration created: db/migrations/20251015194500_add_age_to_users.rb
+```
+
+The generated file looks like this:
+
+```ruby
+# db/migrations/20251015194500_add_age_to_users.rb
+# This file is auto-generated.
+
+def up
+  add_column(:users, :age, :integer)
+end
+
+def down
+  remove_column(:users, :age)
+end
+```
+
+**Step 3: Run the Migration**
+The generated file is perfect. Now, just apply it to your database.
+
+```bash
+dami db migrate
+```
+
+That's it\! Your database is now in sync with your models. This workflow also handles removing columns, adding tables, and even **automatically creating indexes** when you add a `belongs_to` relationship.
+
+-----
+
+## The CLI Commands 🚀
+
+All migration and schema tasks are handled through the `dami` executable.
+
+| Command                          | Description                                                              |
+|----------------------------------|--------------------------------------------------------------------------|
+| `dami db migrate`                | Runs all pending migrations and updates `db/schema.rb`.                  |
+| `dami db rollback [STEPS]`       | Reverts the last migration (or the last `STEPS` migrations).             |
+| `dami generate migration NAME`   | **(Your primary tool)** Generates a new migration from model changes.    |
+| `dami db schema_dump`            | Manually regenerates `db/schema.rb` from the current database state.     |
+
+-----
+
+## Manual Migrations
+
+For complex changes that the generator can't infer—like data migrations, complex constraints, or custom SQL—you can always write a migration by hand.
+
+1.  Create a new file: `db/migrations/TIMESTAMP_do_something_special.rb`.
+2.  Write your `up` and `down` methods using the Schema DSL.
+
+### The Schema DSL
+
+The DSL provides simple methods for all common schema operations.
+
+| Method           | Example Usage                                    |
+|------------------|--------------------------------------------------|
+| `create_table`   | `create_table(:posts) { \|t\| t.field ... }`    |
+| `drop_table`     | `drop_table(:posts)`                             |
+| `add_column`     | `add_column(:users, :status, :string)`           |
+| `remove_column`  | `remove_column(:users, :status)`                 |
+| `add_index`      | `add_index(:posts, :user_id)` / `add_index(:users, :email, unique: true)` |
+| `remove_index`   | `remove_index(:posts, :user_id)`                 |
+| `execute(sql)`   | Runs a raw SQL command for special cases.        |
+
+### Column options
+
+Every `t.field` (and `add_column`) accepts these options, which become real SQL constraints:
+
+| Option                    | Effect                                                     |
+|---------------------------|------------------------------------------------------------|
+| `null: false`             | `NOT NULL`                                                 |
+| `unique: true`            | `UNIQUE`                                                   |
+| `default: value`          | `DEFAULT value` (`default: :current_timestamp` for `CURRENT_TIMESTAMP`) |
+| `references: :users`      | `REFERENCES users(id)` — enforced, Dami turns foreign keys on |
+| `on_delete: :cascade`     | Adds `ON DELETE CASCADE` to a `references:` column         |
+
+```ruby
+create_table(:expenses) do |t|
+  t.field :id, :primary_key
+  t.field :amount_cents, :integer, null: false
+  t.field :currency, :string, null: false, default: 'EUR'
+  t.field :note, :text
+  t.references :batch, on_delete: :cascade   # batch_id INTEGER REFERENCES batches(id) ON DELETE CASCADE
+  t.timestamps                                # created_at / updated_at, filled automatically
+end
+add_index(:expenses, :batch_id)
+```
+
+Violations raise `Dami::NotNullViolation`, `Dami::UniqueConstraintViolation` (with `.column`) and `Dami::ForeignKeyViolation`.
+
+**SQLite limits on `add_column`:** SQLite cannot add a `UNIQUE` or `PRIMARY KEY` column to an existing table, and a `NOT NULL` column added later needs a `default:`. Put those constraints in `create_table`, or add the column and then an index with `add_index(..., unique: true)`.
+
+### Types
+
+| Type(s)                          | SQL type   |
+|----------------------------------|------------|
+| `:primary_key`                   | `INTEGER PRIMARY KEY AUTOINCREMENT` |
+| `:integer`, `:boolean`           | `INTEGER`  |
+| `:float`, `:decimal`             | `REAL`     |
+| `:datetime`, `:date`, `:time`    | `DATETIME` |
+| `:string`, `:text`, `:json`      | `TEXT`     |
+
+Values come back from SQLite as they are stored: booleans are converted for fields declared `:boolean`, JSON is parsed for fields declared `:json`, dates and times come back as strings (`'2026-09-12'`, `'2026-09-12 18:40:00'` UTC).
+
+-----
+
+## The Role of `db/schema.rb`
+
+This file is a critical part of the generator. It's an auto-generated snapshot of your database's canonical structure after the last successful migration.
+
+  * **DO NOT EDIT THIS FILE MANUALLY.**
+  * Dami uses it as the "before" picture to compare against your "after" models.
+  * It's automatically updated for you every time you run `dami db:migrate`.
+  * You should commit this file to your version control system (Git).
+
+-----
+
+## Best Practices
+
+  * **Trust the Generator First**: Always try to use `dami generate migration` as your primary workflow. It's faster and less error-prone.
+  * **Write Manual Migrations for Data Changes**: The generator handles structure (schema), but you should write manual migrations for data changes (e.g., backfilling a `status` column for existing users).
+  * **Never Edit a Run Migration**: Once a migration has been run on other machines, do not edit it. Create a *new* migration to make further changes.
+
+## What's Next?
+
+  * **Chapter 10: Advanced Topics** - Explore transactions, flows, and other powerful features for building complex application logic.

data/docs/10.Flows_and_Commands.md

@@ -0,0 +1,181 @@
+## Chapter 10: Drafts, Flows & Commands
+
+In most frameworks, handling business logic is an afterthought. It gets mixed into models, controllers, or scattered across service objects. Dami treats business logic as a first-class citizen with a simple, powerful philosophy: the **"Spectrum of Complexity."**
+
+A great framework shouldn't give you a sledgehammer for every task. It should give you a full toolbox. Dami provides the perfect tool for every job, scaling gracefully from a simple one-liner to a complex, orchestrated workflow.
+
+This chapter will guide you through the three tiers of Dami's business logic layer.
+
+-----
+
+### Tier 1: The Foot Soldier - Simple, Direct CRUD
+
+**When to use it:** For trusted, internal operations where no complex validation is needed. An admin script, a database seed, or a simple counter update.
+
+For these tasks, Dami gets out of your way. The tool is a direct, one-liner database command. There is no ceremony.
+
+```ruby
+# Fast, simple, and explicit.
+# No extra layers needed for trusted operations.
+
+# Activate a user
+db(:users).where(id: 1337).update(status: 'active')
+
+# Log a user's last login time
+db(:users).find(42).update(last_seen_at: Time.now)
+
+# Delete archived records
+db(:orders).where(status: 'archived').delete
+```
+
+This is the baseline. It's clean, performant, and the right tool for simple jobs.
+
+-----
+
+### Tier 2: The Elite Guard - Inline Drafts
+
+**When to use it:** For the 80% of typical web controller actions. A user updates their profile, submits a form, or changes a setting. The input is untrusted and requires contextual validation and transformation.
+
+For these tasks, Dami provides an **inline `draft` block** on `create`, `update`, and `delete`. This is a massive leap in power with minimal ceremony. It gives you a temporary `draft` object to prepare and verify your data within a single, atomic transaction.
+
+```ruby
+# app/controllers/accounts_controller.rb
+def update
+  # ...
+  # The block yields a `draft` object. The entire block is one transaction.
+  updated_account = db(:accounts).where(id: params[:id]).update(params) do |draft|
+    # --- The Inline Draft DSL ---
+
+    # 1. Use declarative helpers for common patterns.
+    draft.prevent_changes :subdomain, message: "Subdomain cannot be changed."
+    
+    # 2. Apply reusable transformations.
+    draft.prepare(AccountPolicies::NORMALIZE_NAME)
+
+    # 3. Add ad-hoc, contextual validation.
+    draft.verify :name_is_unique, error: "This name is already taken." do
+      # `changed?` and `original` are available helpers.
+      !draft.changed?(:name) || db(:accounts).where(name: draft.get(:name)).none?
+    end
+  end
+
+  if updated_account
+    # The block passed, and the update was successful.
+    redirect_to account_path, notice: "Account updated!"
+  else
+    # The block failed validation and halted. `update` returns nil.
+    # The database was never touched.
+    render :edit, status: :unprocessable_entity
+  end
+end
+```
+
+This is the workhorse of your application. It provides contextual validation and transformation right where it's needed, using a consistent, declarative DSL.
+
+-----
+
+### Tier 3: The Final Boss - Commands & Orchestration
+
+**When to use it:** For the 20% of critical, multi-step business processes. A user signup, an e-commerce checkout, a subscription cancellation. These workflows involve multiple database tables, external API calls, and side effects that **cannot be rolled back**.
+
+For these tasks, Dami provides two powerful tools: **Commands** and **`Dami.run`**.
+
+#### The Command (The Brains 🧠)
+
+A `Dami::Command` encapsulates complex validation and transformation logic into a single, reusable, and testable class. It's how you turn the logic from an inline block into a formal, named "recipe."
+
+```ruby
+# app/commands/create_account_and_owner_command.rb
+class CreateAccountAndOwnerCommand < Dami::Command
+  # Fails early if `signup_source` is not provided in the context.
+  requires_context :signup_source
+
+  # Declarative validation rules for the incoming data.
+  validate :account_name_is_unique, error: "Account name is taken" do
+    db(:accounts).where(name: data[:account][:name]).none?
+  end
+
+  validate :owner_password_confirmation, error: "Passwords do not match" do
+    data[:user][:password] == data[:user][:password_confirmation]
+  end
+
+  # A data transformation step.
+  transform :prepare_records do |data|
+    data[:user][:password_hash] = BCrypt::Password.create(data[:user][:password])
+    data[:account][:subdomain] = data[:account][:name].downcase.strip.gsub(/\s+/, '-')
+    data
+  end
+end
+```
+
+#### The Orchestrator (`Dami.run`)
+
+This is the final boss. It's a top-to-bottom, transaction-safe orchestrator for the entire business process. It reads like a clear, imperative script.
+
+```ruby
+# app/flows/onboarding_flow.rb
+Dami.run(context: { signup_source: 'web' }) do |run_context|
+  # 1. PREPARE the data. `prepare` uses the command to validate and transform.
+  #    It halts automatically if validation fails.
+  clean_data = prepare CreateAccountAndOwnerCommand, with: params, context: run_context
+
+  # 2. Interact with the DB. These commands are now part of the `run` block's
+  #    single, atomic transaction.
+  account = db(:accounts).create(clean_data[:account])
+  user = db(:users).create(clean_data[:user].merge(account_id: account[:id]))
+
+  # 3. Perform an external task with resilience.
+  perform "Create Billing Trial", retry: { on: [Billing::ApiError], times: 3 } do
+    BillingService.start_trial(account_id: account[:id], user_email: user[:email])
+  end
+
+  # 4. SUCCEED. The final, declarative exit point for the entire orchestration.
+  succeed with: { account: account, user: user }, and_then: [
+    WelcomeEmailJob.with(user_id: user.id),
+    Analytics.track("Team Onboarded", account_id: account.id)
+  ]
+end
+```
+
+-----
+
+### **The Dami Guarantee: Atomic Operations & Safe Side Effects**
+
+You might be asking: "Why do I need `succeed with: and_then:`? Can't I just put the email job in a `call` block?" This is where Dami's most powerful feature comes into play.
+
+#### The Problem: The "Email Sent, User Never Created" Bug
+
+A `Dami.run` block guarantees that all **database operations** are atomic—they all succeed, or they all roll back. That includes a `Failure` halt from `prepare`: every write the flow made before the halt is rolled back. A flow that calls `run(:other_flow)` runs the inner flow in a savepoint, so an inner failure rolls back only the inner writes and hands the `Failure` back to the outer flow. But what about actions that can't be rolled back, like sending an email or enqueuing a background job?
+
+**Consider this dangerous sequence of events:**
+
+1.  A user is created in the database transaction.
+2.  A welcome email job is immediately enqueued.
+3.  The *next step*, calling the `BillingService`, fails.
+4.  **Disaster:** The entire database transaction is **rolled back**. The user record is deleted. But it's too late—the email job is already in the queue, and a welcome email gets sent to a user who doesn't exist.
+
+#### The Dami Solution: A Transaction-Aware Holding Area
+
+The `succeed with: and_then:` block is not just another step. It is a **transaction-aware gatekeeper** for your irreversible side effects.
+
+> It's a "holding area" for actions that must only run *after* the database transaction has been successfully and permanently committed.
+
+**This is the safe, correct sequence:**
+
+1.  A user is created in the database transaction.
+2.  The call to the `BillingService` succeeds.
+3.  The `succeed with:` block is reached. The `WelcomeEmailJob` is placed in the holding area.
+4.  The `Dami.run` block finishes. Dami commits the database transaction.
+5.  **Only now**, after the commit is successful, does Dami execute the actions in the `and_then:` block.
+
+If the `BillingService` had failed, the transaction would have rolled back, and the `and_then:` block would have been discarded. No email would ever be sent.
+
+---
+
+### The Dami Way vs. The Rails Way
+
+  * **The Problem: Callback Hell & Fat Models.** In Rails, a complex process like this is often a chain of `after_save` hooks. An `Account` model might trigger a user creation, which in turn triggers a welcome email. This chain of hidden actions is brittle and incredibly hard to debug. If an API call to the `BillingService` fails, the `Account` and `User` records are already in the database, leaving your system in an inconsistent, half-finished state.
+
+  * **The Dami Solution: An Explicit, Transactional Orchestrator.** `Dami.run` makes the entire business process visible and atomic. The "semantic trio" of `prepare`, `db()`, and `call` makes the intent of each line instantly clear. If the `call` to the `BillingService` fails, the entire transaction is **automatically rolled back**, and the `Account` and `User` records are never saved. The `succeed with: and_then:` block guarantees that side effects like sending an email happen **only after** everything has been successfully committed to the database, eliminating an entire class of common bugs.
+
+This is the pinnacle of the Dami philosophy: a system that scales from the simplicity of a one-liner to the robust, transactional, and resilient power needed for mission-critical business logic, all while maintaining a consistent and joyful developer experience.