dami 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d27e7d5a72541d63d026ed24e418d0acc195bf33d724f6086afcfece355998b
-  data.tar.gz: eadb86a3f0a4aae782971785f3c180a532d30561b82fe23f43d8fe236d0724af
+  metadata.gz: 5e550fe4dbb3da8996d88b0825c92f2208cb60bdf5c6d389b610de8d65d22091
+  data.tar.gz: 35464adbc1ab5319602ef98276c1a6002cba6fbc313ae9c3e2288b970d08f0ab
 SHA512:
-  metadata.gz: 4a636d87228fb6e1ad6d8b83d7c101bec962423647cf096650b5026e9242776005c64287ad19817ea9a0474b64227a5282d290ff15aa802ea555c5784ffdafd4
-  data.tar.gz: a2cbe7c1417947fdc97876875de4aafba02a6cf326ff3a429f11feb7ba48db3908a33208a12c763160fe7d2c61334e22a63aaaf67bdfd85d1b1afe52682b245b
+  metadata.gz: ff82a43bd0a072525a74339037cb84525034dd16c6c13279971db061d51556a28e790d3cfe1e0b64c3e79d64a56e300c1f44418c8b741a787c880a140a73502c
+  data.tar.gz: 3fad29facc198fea952c6e79f7917af916104c0e7fac41ccb7971225083fb6a96a8cc2574e4349877d76c1e81e5127b80f7234efa2026d7a88a27c69ad761f68

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [1.0.1] - 2026-09-13
+
+Found while building the first app on 1.0.0 (a finance app on aris + dami, 98 tests), then a full read of the docs against the source.
+
+### 🐛 Correctness
+
+* **Text arriving as binary is stored as text.** Rack hands a web app its params as ASCII-8BIT strings, and the sqlite3 gem binds a binary string as a BLOB, which never equals the TEXT it looks like: the row is written, then `where(name: params['name'])` finds nothing. A binary string whose bytes are valid UTF-8 is now bound as text on every path (`execute`, `get_first_row`, prepared statements, inserts). Bytes that are not valid UTF-8 (an image, a PDF) still go in as a BLOB.
+* **`Migration#execute` exists.** The docs listed it; the class did not define it. `execute(sql, params = [])` runs raw SQL inside the migration's transaction: triggers, views, PRAGMAs, data fixes.
+* **`db(:model)` inside `Command` validations and `Draft` blocks.** The docs' `verify :name_is_unique` examples called `db(...)` from inside a block that is `instance_exec`'d on the draft or command, where no `db` existed. Both have it now.
+* **`none?` on a query**, the opposite of `any?`. The docs used it; the builder did not have it.
+
+### 📚 Docs
+
+* Chapter 10 (Drafts, Flows & Commands) now shows the real API: `Dami.flow :name do ... end` + `Dami.run(:name, **params)` (the chapter showed a `Dami.run(context: ...) do |run_context|` form that never existed), `draft.transform` / `draft.apply` (not `draft.prepare`), `perform ..., retry_options: { on:, times: }` (not `retry:`), `and_then:` takes callables, results are `Success`/`Failure` with `value` / `error`. Draft blocks are on `create` and `update`, not `delete`. The flow snippets in `Manifesto.md` and `site.md` showed a `step` DSL that does not exist; they use the real one now.
+* Chapter 12 (The Dami Way): an AI reply that had been pasted in above the chapter ("Absolutely. This is the perfect way to end the documentation…") is gone, together with the ````markdown fence that rendered the chapter's opening as a code block. Its examples use `protection` (there is no `before(:save)`) and the real flow API.
+* Chapter 5: `when:` is equality only; use `if:` for anything else. Chapter 9: `execute` signature. Chapter 3: `none?`. Chapter 8/9: the link to chapter 10 names the right chapter.
+* Stray "THE FIX:" / "no changes needed" comments left by AI-assisted editing removed from `lib/` and `test/`. One of them was an empty duplicate `test_create_table_and_reverse` that shadowed the real test; the real one runs again.
+
+### ✅ Tests
+
+284 tests. New: `test/encoding_test.rb` (binary text stored as TEXT and matching in `where`; non-UTF-8 bytes stay a BLOB), `Migration#execute` with params and a trigger, `db` from a draft and from a command validation.
+
 ## [1.0.0] - 2026-09-12 (pre-publish review pass)
 
 Fixes applied after a full review of the 1.0.0 working tree, before the first

data/docs/03.Querying.md

@@ -197,6 +197,11 @@ if Dami.db(:users).where(status: 'pending').any?
   puts "There are pending users to review."
 end
 
+# `none?` is the opposite
+if Dami.db(:users).where(email: email).none?
+  puts "That email is free."
+end
+
 # `exists?` is a convenient alias
 if Dami.db(:users).exists?(status: 'pending')
   puts "There are pending users to review."
@@ -229,7 +234,7 @@ Queries are **lazy**. They are only sent to the database when you ask for the da
   - `.first`
   - `.last`
   - `.count`
-  - `.any?` / `.exists?`
+  - `.any?` / `.exists?` / `.none?`
   - `.each`
   - `.find_each`
   - `.find_in_batches`
@@ -372,6 +377,7 @@ A concise summary of the Dami query DSL.
 | `.each { \|rec\| ... }` | Executes the query and yields each record.             |
 | `.count`                | Executes a `COUNT` query for the conditions.           |
 | `.any?`, `.exists?`     | Executes a `LIMIT 1` query to check for existence.     |
+| `.none?`                | The opposite of `.any?`.                               |
 
 ### Batch Processing
 

data/docs/04.Creating_Updating_Deleting.md

@@ -168,7 +168,7 @@ Dami.model :comments do
   fields { field :post_id, :integer; field :content, :text }
   relationships { belongs_to :post }
 end
-````
+```
 
 The `allow_destroy: true` option is required if you want to allow nested records to be deleted.
 

data/docs/05.Validation.md

@@ -190,7 +190,7 @@ end
 
 ### Using `when:`
 
-For simple equality checks, `when:` provides a convenient shortcut. The rule only runs if the attributes in the `when` hash match the record's attributes.
+For simple equality checks, `when:` provides a convenient shortcut. The rule only runs if every attribute in the `when` hash equals the value being saved. It is equality only; anything more (a range, a regex, another record) is an `if:` lambda.
 
 ```ruby
 Dami.behavior :orders do

data/docs/08.Scopes.md

@@ -96,4 +96,4 @@ Scopes are a fundamental tool for writing clean and maintainable data-access cod
 ## 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.
+  * **Chapter 10: Drafts, Flows & Commands** - Business logic: inline drafts, commands, and transactional flows.

data/docs/09.Migrations.md

@@ -99,7 +99,7 @@ The DSL provides simple methods for all common schema operations.
 | `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.        |
+| `execute(sql, params = [])` | Raw SQL for what the DSL does not cover: `execute("CREATE TRIGGER ...")`, `execute("UPDATE users SET status = ? WHERE status IS NULL", ['active'])` |
 
 ### Column options
 
@@ -162,4 +162,4 @@ This file is a critical part of the generator. It's an auto-generated snapshot o
 
 ## What's Next?
 
-  * **Chapter 10: Advanced Topics** - Explore transactions, flows, and other powerful features for building complex application logic.
+  * **Chapter 10: Drafts, Flows & Commands** - Business logic: inline drafts, commands, and transactional flows.

data/docs/10.Flows_and_Commands.md

@@ -1,4 +1,4 @@
-## Chapter 10: Drafts, Flows & Commands
+# 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."**
 
@@ -36,26 +36,27 @@ This is the baseline. It's clean, performant, and the right tool for simple jobs
 
 **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.
+For these tasks, Dami provides an **inline `draft` block** on `create` and `update`. This is a massive leap in power with minimal ceremony. It gives you a temporary `draft` object to prepare and verify your data before anything is written.
 
 ```ruby
-# app/controllers/accounts_controller.rb
+# In a request handler
 def update
   # ...
-  # The block yields a `draft` object. The entire block is one transaction.
+  # The block yields a `draft` object. It runs first; only if it passes does
+  # the write happen, in 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.
+    # 2. Transform the data. The block returns the new data hash.
+    draft.transform(:normalize_name) { |data| data.merge(name: data[:name].strip) }
+
+    # 3. Add ad-hoc, contextual validation. `db`, `get`, `changed?` and
+    #    `original` are available inside the block.
     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?
+      !changed?(:name) || db(:accounts).where(name: get(:name)).none?
     end
   end
 
@@ -70,6 +71,10 @@ def update
 end
 ```
 
+A reusable transformation is a callable that receives the draft: `draft.apply(AccountPolicies::NORMALIZE_NAME)` with `NORMALIZE_NAME = ->(d) { d.transform(:normalize_name) { |data| data.merge(name: data[:name].strip) } }`.
+
+`create` with a failing draft raises `Dami::ValidationError` (there is no record to return); `update` returns `nil`.
+
 This is the workhorse of your application. It provides contextual validation and transformation right where it's needed, using a consistent, declarative DSL.
 
 -----
@@ -78,7 +83,7 @@ This is the workhorse of your application. It provides contextual validation and
 
 **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`**.
+For these tasks, Dami provides two powerful tools: **Commands** and **Flows**.
 
 #### The Command (The Brains 🧠)
 
@@ -87,10 +92,10 @@ A `Dami::Command` encapsulates complex validation and transformation logic into
 ```ruby
 # app/commands/create_account_and_owner_command.rb
 class CreateAccountAndOwnerCommand < Dami::Command
-  # Fails early if `signup_source` is not provided in the context.
+  # Fails early if `signup_source` is not in the context.
   requires_context :signup_source
 
-  # Declarative validation rules for the incoming data.
+  # Declarative validation rules for the incoming data. `db` is available.
   validate :account_name_is_unique, error: "Account name is taken" do
     db(:accounts).where(name: data[:account][:name]).none?
   end
@@ -99,53 +104,70 @@ class CreateAccountAndOwnerCommand < Dami::Command
     data[:user][:password] == data[:user][:password_confirmation]
   end
 
-  # A data transformation step.
+  # A data transformation step. It returns the changes, merged into the data.
   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
+    {
+      user: data[:user].merge(password_hash: BCrypt::Password.create(data[:user][:password])),
+      account: data[:account].merge(subdomain: data[:account][:name].downcase.strip.gsub(/\s+/, '-')),
+    }
   end
 end
 ```
 
-#### The Orchestrator (`Dami.run`)
+A command can also be run on its own: `CreateAccountAndOwnerCommand.new(data: attrs, context: { signup_source: 'web' }).call` returns the command, with `valid?`, `errors` and the transformed `data`.
 
-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.
+#### The Orchestrator (`Dami.flow` + `Dami.run`)
+
+This is the final boss. A flow is 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
+# app/flows/onboarding.rb
+Dami.flow :onboard_team do
+  # 1. PREPARE the data. `prepare` runs the command on `params`, with everything
+  #    passed to Dami.run as the command's context. It halts if validation fails.
+  clean = prepare CreateAccountAndOwnerCommand, with: params
 
-  # 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]))
+  # 2. Interact with the DB. Every write in the flow is part of one atomic transaction.
+  account = db(:accounts).create(clean[:account])
+  user    = db(:users).create(clean[:user].merge(account_id: account[:id]))
 
   # 3. Perform an external task with resilience.
-  perform "Create Billing Trial", retry: { on: [Billing::ApiError], times: 3 } do
+  perform "Create Billing Trial", retry_options: { 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.
+  # 4. SUCCEED. The final, declarative exit point. `and_then:` takes callables;
+  #    they run only after the transaction has committed.
   succeed with: { account: account, user: user }, and_then: [
-    WelcomeEmailJob.with(user_id: user.id),
-    Analytics.track("Team Onboarded", account_id: account.id)
+    -> { WelcomeEmailJob.perform_later(user_id: user[:id]) },
+    -> { Analytics.track("Team Onboarded", account_id: account[:id]) }
   ]
 end
 ```
 
+Run it from anywhere. Keyword arguments become the flow's params, each readable by name inside the flow (`params`, `signup_source`):
+
+```ruby
+result = Dami.run(:onboard_team, params: form_params, signup_source: 'web')
+
+if result.success?
+  result.value[:account]   # whatever `succeed with:` was given
+else
+  result.error             # the command's errors, e.g. { account_name_is_unique: ["Account name is taken"] }
+end
+```
+
+A flow can call another flow with `run(:other_flow, extra: 'params')`; the inner flow runs in a savepoint and returns its own `Success` or `Failure`. `halt(value)` leaves a flow early with any value.
+
 -----
 
 ### **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.
+You might be asking: "Why do I need `succeed with: and_then:`? Can't I just put the email job in a `perform` 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?
+A flow run with `Dami.run` 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:**
 
@@ -165,7 +187,7 @@ The `succeed with: and_then:` block is not just another step. It is a **transact
 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.
+4.  The flow 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.
@@ -176,6 +198,6 @@ If the `BillingService` had failed, the transaction would have rolled back, and
 
   * **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.
+  * **The Dami Solution: An Explicit, Transactional Orchestrator.** `Dami.run` makes the entire business process visible and atomic. The "semantic trio" of `prepare`, `db()`, and `perform` makes the intent of each line instantly clear. If the `perform` step calling 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.

data/docs/11.Localization.md

@@ -28,7 +28,7 @@ Dami.localize :validations do
     set :min_length, ->(min) { "es demasiado corto (mínimo: #{min} caracteres)" }
   end
 end
-````
+```
 
 This approach is powerful because it's pure Ruby. You can load these definitions from anywhere, and it's completely explicit—no "magic" `method_missing`.
 

data/docs/12.TheDamiWay.md

@@ -1,12 +1,3 @@
-Absolutely. This is the perfect way to end the documentation—a confident, opinionated "manifesto" that clearly articulates Dami's superior design philosophy. Your draft is a great start, and we can definitely crank up the energy to get developers hyped.
-
-You're right, the draft is missing the knockout punches about validations and other key differentiators. Let's upgrade this from a simple comparison to a powerful final statement.
-
-Here is the revised, high-energy final chapter.
-
------
-
-````markdown
 # Chapter 12: The Dami Way - A Manifesto
 
 You've learned the "what" of Dami's features. This final chapter is about the "why." It's a declaration of the principles that make Dami a fundamentally better way to build modern, maintainable applications.
@@ -43,7 +34,7 @@ class User < ApplicationRecord
   end
   # ... 500 more lines of tangled logic ...
 end
-````
+```
 
 #### **The Dami Way: The Four Pillars of Clarity**
 
@@ -56,7 +47,7 @@ Dami makes this architectural mess impossible **by design**. It provides four di
 Dami.model(:users) { fields { ... }; relationships { ... } }
 
 # --- 2. Behavior (The Internal Rules) ---
-Dami.behavior(:users) { validate { ... }; before(:save) { ... } }
+Dami.behavior(:users) { validate { ... }; protection { ... } }
 
 # --- 3. Presentation (The Public Interface) ---
 Dami.present(:users) { def full_name; ...; end }
@@ -150,13 +141,13 @@ Dami's **Flows** make the entire business process visible, atomic, and safe. It
 
 ```ruby
 # The Dami Way: An Explicit, Readable, and Resilient Script
-Dami.run(:user_signup_flow) do
+Dami.flow :user_signup do
   # 1. Validate and prepare all incoming data
   clean_data = prepare CreateUserCommand, with: params
 
   # 2. Run all database operations inside a single, atomic transaction
-  user = db(:users).create(clean_data[:user])
-  db(:teams).default.add_member(user)
+  user = db(:users).create(clean_data)
+  db(:memberships).create(user_id: user[:id], team_id: default_team_id)
 
   # 3. Perform external actions with built-in resilience
   perform "Sync to CRM", retry_options: { on: [Crm::ApiError], times: 2 } do
@@ -165,9 +156,11 @@ Dami.run(:user_signup_flow) do
 
   # 4. Safely enqueue side effects ONLY AFTER the transaction commits
   succeed with: user, and_then: [
-    WelcomeEmailJob.with(user_id: user[:id])
+    -> { WelcomeEmailJob.perform_later(user_id: user[:id]) }
   ]
 end
+
+result = Dami.run(:user_signup, params: form_params, default_team_id: 1)
 ```
 
 ### **The Shootout: Why Dami Wins Decisively**

data/docs/Manifesto.md

@@ -139,30 +139,24 @@ end
 Dami replaces this invisible chaos with **explicit, readable, transactional workflows**:
 
 ```ruby
-Dami.flow :user_onboarding do |params|
-  step :create_user do
-    user = db[:users].create(params)
-    set(:user, user)
-  end
-  
-  step :send_welcome_email do
-    UserMailer.welcome(get(:user)[:email]).deliver
-  end
-  
-  step :track_analytics do
-    Analytics.track('signup', user_id: get(:user)[:id])
-  end
-  
-  step :activate_subscription do
-    Stripe.create_subscription(customer: get(:user)[:email])
+Dami.flow :user_onboarding do
+  user = db(:users).create(params)
+
+  perform "Activate subscription", retry_options: { on: [Stripe::APIError], times: 2 } do
+    Stripe.create_subscription(customer: user[:email])
   end
+
+  succeed with: user, and_then: [
+    -> { UserMailer.welcome(user[:email]).deliver },
+    -> { Analytics.track('signup', user_id: user[:id]) }
+  ]
 end
 
 # Execute the entire workflow
-Dami.run(:user_onboarding, name: 'Alice', email: 'alice@example.com')
+Dami.run(:user_onboarding, params: { name: 'Alice', email: 'alice@example.com' })
 ```
 
-What happens if step 3 fails? **The entire transaction rolls back.** Your database stays consistent. Your user doesn't get created. No orphaned records. No mystery states.
+What happens if Stripe fails? **The entire transaction rolls back.** Your database stays consistent. Your user doesn't get created. No orphaned records. No mystery states.
 
 This is the **Dami Guarantee**: atomic workflows or nothing.
 

data/docs/site.md

@@ -137,11 +137,13 @@ Dami compares model to schema. Writes perfect, reversible migrations. **The tedi
 Rails callbacks scatter logic across time and space. Dami makes business logic **explicit and atomic:**
 
 ```ruby
-Dami.flow :user_onboarding do |params|
-  step :create_user { db[:users].create(params) }
-  step :send_email { Mailer.welcome(user) }
-  step :track_event { Analytics.track('signup') }
-  step :sync_crm { CRM.sync(user) }
+Dami.flow :user_onboarding do
+  user = db(:users).create(params)
+  perform("Sync CRM") { CRM.sync(user) }
+  succeed with: user, and_then: [
+    -> { Mailer.welcome(user) },
+    -> { Analytics.track('signup') }
+  ]
 end
 ```
 
@@ -315,10 +317,12 @@ Dami.behavior :users do
 end
 
 # Flow
-Dami.flow :signup do |params|
-  step(:create) { db[:users].create(params) }
-  step(:email) { Mailer.welcome(user) }
-  step(:track) { Analytics.track('signup') }
+Dami.flow :signup do
+  user = db(:users).create(params)
+  succeed with: user, and_then: [
+    -> { Mailer.welcome(user) },
+    -> { Analytics.track('signup') }
+  ]
 end
 ```
 

data/lib/dami/actions/command.rb

@@ -44,6 +44,10 @@ module Dami
       sym_field = field.to_sym
       @data.key?(sym_field) && @original[sym_field] != @data[sym_field]
     end
+    # The database, so a validation can check it: db(:accounts).where(name: data[:name]).none?
+    def db(model_name)
+      Dami.db(model_name)
+    end
     private
     def validate_required_context!
       missing = (self.class.instance_variable_get(:@required_context) || []) - @context.keys
@@ -66,11 +70,10 @@ module Dami
         end
       end
     end
-def run_transformations
+    def run_transformations
       current_data = @data.dup
       (self.class.instance_variable_get(:@transformations) || []).each do |t|
-        # THE FIX: Each transform block returns a hash of changes.
-        # We must MERGE these changes into the current data hash.
+        # Each transform block returns a hash of changes, merged into the data.
         result = instance_exec(current_data, &t[:block])
         current_data.merge!(result) if result.is_a?(Hash)
       end

data/lib/dami/actions/context.rb

@@ -15,20 +15,19 @@ module Dami
       halt(Dami::Failure.new(command.errors)) unless command.valid?
       command.data
     end
-    # THE FIX IS HERE: Renamed 'retry:' to 'retry_options:'
+    # A step that talks to the outside world. retry_options: { on: [SomeError], times: 2 }
+    # retries that many times on those exceptions; timeout: is in seconds.
     def perform(name, retry_options: {}, timeout: nil, &block)
       action = -> do
-        # THE FIX: Use the new parameter name 'retry_options'
         retry_exceptions = Array(retry_options[:on])
-        # Add 1 for the initial attempt.
-        max_attempts = (retry_options[:times] || 0) + 1
+        max_attempts = (retry_options[:times] || 0) + 1   # the first attempt plus the retries
         attempts = 0
         begin
           attempts += 1
           block.call
         rescue *retry_exceptions => e
           raise if attempts >= max_attempts
-          retry # This 'retry' keyword is correct because it's inside the rescue block
+          retry
         end
       end
       if timeout

data/lib/dami/actions/draft.rb

@@ -32,5 +32,9 @@ module Dami
     def valid?
       @errors.empty?
     end
+    # The database, so a verify block can check it: db(:accounts).where(name: get(:name)).none?
+    def db(model_name)
+      Dami.db(model_name)
+    end
   end
 end

data/lib/dami/actions/flow.rb

@@ -17,7 +17,6 @@ module Dami
       @after_commit_hooks = []
     end
 
-    # Fix: Ensure the method accepts the context parameter
     def call(context)
       context.instance_exec(&@block)
     rescue => e

data/lib/dami/adapters/sqlite/connection.rb

@@ -87,6 +87,7 @@ module SqliteConnection
 
   def convert_value(value)
     case value
+    when String then text_or_blob(value)
     when Time then value.utc.strftime('%Y-%m-%d %H:%M:%S')
     when DateTime then value.to_time.utc.strftime('%Y-%m-%d %H:%M:%S')
     when Date then value.to_s
@@ -96,6 +97,17 @@ module SqliteConnection
     end
   end
 
+  # Rack hands a web app its params as ASCII-8BIT strings, and the sqlite3 gem
+  # binds a binary string as a BLOB, which never equals the TEXT it looks like:
+  # the row is written, then `where(name: params['name'])` finds nothing. A
+  # binary string whose bytes are valid UTF-8 is text, so it is bound as text.
+  # Bytes that are not valid UTF-8 (an image, a PDF) still go in as a BLOB.
+  def text_or_blob(value)
+    return value unless value.encoding == Encoding::ASCII_8BIT
+    text = value.dup.force_encoding(Encoding::UTF_8)
+    text.valid_encoding? ? text : value
+  end
+
   def handle_sqlite_error(error, sql: nil)
     msg = error.message
     if msg.include?('UNIQUE constraint failed')

data/lib/dami/core.rb

@@ -24,7 +24,7 @@ def self.clear_all!
 
 def self.present(model_name, &block)
   presenter_module = Module.new
-  presenter_module.module_eval(&block)  # Changed from instance_eval
+  presenter_module.module_eval(&block)
   (@presenter_modules ||= {})[model_name] = presenter_module
 end
 

data/lib/dami/inflector.rb

@@ -32,7 +32,7 @@ module Dami
       'paralysis' => 'paralyses', 'parenthesis' => 'parentheses', 'synopsis' => 'synopses',
       'thesis' => 'theses', 'phenomenon' => 'phenomena', 'criterion' => 'criteria',
       'datum' => 'data',
-      # Add the common -s words as irregular to handle them explicitly
+      # common -s words, listed as irregular so they are handled explicitly
       'bus' => 'buses', 'gas' => 'gases', 'lens' => 'lenses', 'glass' => 'glasses',
       'class' => 'classes', 'mass' => 'masses', 'grass' => 'grasses', 'brass' => 'brasses',
       'canvas' => 'canvases', 'atlas' => 'atlases', 'bias' => 'biases', 'cosmos' => 'cosmoses',

data/lib/dami/migration.rb

@@ -1,41 +1,41 @@
-# lib/dami/migration.rb - Fix create_table to support block parameter syntax
+# lib/dami/migration.rb — the schema DSL a migration file's up/down is written in
 
 module Dami
   class Migration
     def initialize(adapter)
       @adapter = adapter
     end
-    
+
     def up
       # This should be overridden by the migration file
     end
-    
+
     def down
-      # This should be overridden by the migration file  
+      # This should be overridden by the migration file
     end
-    
+
     # Schema methods
-def create_table(name, &block)
-  table_definition = TableDefinition.new
-  
-  # Support both styles: do |t| ... end and do ... end
-  if block.arity == 0
-    table_definition.instance_eval(&block)
-  else
-    yield table_definition
-  end
-  
-  @adapter.create_table(name, table_definition.columns)
-end
-    
+    def create_table(name, &block)
+      table_definition = TableDefinition.new
+
+      # Support both styles: do |t| ... end and do ... end
+      if block.arity == 0
+        table_definition.instance_eval(&block)
+      else
+        yield table_definition
+      end
+
+      @adapter.create_table(name, table_definition.columns)
+    end
+
     def drop_table(name)
       @adapter.execute("DROP TABLE IF EXISTS #{name}")
     end
-    
+
     def add_column(table, column, type, **options)
       @adapter.add_column(table, column, type, **options)
     end
-    
+
     def remove_column(table, column)
       # SQLite has limited DROP COLUMN support
       # This will work in SQLite 3.35.0+ but fail gracefully in older versions
@@ -46,6 +46,7 @@ end
         puts "Note: DROP COLUMN not supported in this SQLite version: #{e.message}"
       end
     end
+
     def add_index(table_name, column_name, **options)
       @adapter.add_index(table_name, column_name, options)
     end
@@ -54,20 +55,26 @@ end
       @adapter.remove_index(table_name, column_name, options)
     end
 
-    
+    # Raw SQL for what the DSL does not cover: triggers, views, PRAGMAs, data
+    # fixes. Runs inside the migration's transaction like every other step.
+    #   execute "CREATE TRIGGER ..."
+    #   execute "UPDATE users SET status = ? WHERE status IS NULL", ['active']
+    def execute(sql, params = [])
+      @adapter.execute(sql, params)
+    end
   end
-  
+
   class TableDefinition
     attr_reader :columns
-    
+
     def initialize
       @columns = []
     end
-    
+
     def field(name, type, **options)
       @columns << { name: name, type: type, **options }
     end
-    
+
     # created_at / updated_at columns. Dami fills them automatically on
     # create/update when the model declares the same two fields.
     def timestamps
@@ -81,4 +88,4 @@ end
       field(:"#{name}_id", :integer, references: table, **options)
     end
   end
-end
+end

data/lib/dami/migrator.rb

@@ -10,7 +10,7 @@ module Dami
     
     def migrate
       pending_migrations.each { |m| run_migration(m) }
-      dump_schema # ADD THIS LINE
+      dump_schema
     end
     
     def rollback(steps = 1)
@@ -69,7 +69,6 @@ module Dami
     def run_migration(migration_info)
       migration = load_migration(migration_info[:file])
       @adapter.transaction do
-        # THE FIX: Call the new method name.
         migration.up
         @adapter.insert_record(:schema_migrations, { version: migration_info[:version] })
       end
@@ -78,7 +77,6 @@ module Dami
     def reverse_migration(migration_info)
       migration = load_migration(migration_info[:file])
       @adapter.transaction do
-        # THE FIX: Call the new method name.
         migration.down
         
         @adapter.execute(

data/lib/dami/plugins/validations.rb

@@ -18,10 +18,9 @@ def validate(value, rule_name, params = [], context = {})
           rule_config = rule.is_a?(Proc) ? rule.call(*params) : rule
           check = rule_config[:check]
           
-          # --- THE FIX: Use the new Dami.translate system ---
           # 1. Use an inline message if provided directly in the rule definition.
           message = rule_config[:message]
-          # 2. Otherwise, fetch it from the new localization system.
+          # 2. Otherwise, fetch it from the localization system.
           message ||= Dami.translate("validations.#{rule_name}", *params)
           # 3. Use a generic fallback if no translation is found.
           message ||= "is invalid"

data/lib/dami/query/enumerable.rb

@@ -47,11 +47,14 @@ module Dami
         adapter.query_exists?(build_query_structure)
       end
 
+      def none?
+        !any?
+      end
+
       def exists?(conds = nil)
         conds ? where(conds).any? : any?
       end
 
-      # This is the updated method
       def count
         adapter.count_records(build_query_structure)
       end

data/lib/dami/query/persistence.rb

@@ -69,7 +69,6 @@ def create_many(records, permit: [], protect: true)
       
       prepared_records << prepared[:db_parent_attrs]
     rescue Dami::ValidationError => e
-      # FIX: Just store the error object, not try to set errors
       all_errors[index] = e.errors
     rescue Dami::ProtectionError, Dami::UnknownFieldsError => e
       raise e
@@ -78,7 +77,6 @@ def create_many(records, permit: [], protect: true)
   
   # If ANY validations failed, raise with collected errors
   unless all_errors.empty?
-    # FIX: Create a custom message and pass errors in the initializer
     message = "Validation failed for #{all_errors.size} record(s): " + 
               all_errors.map { |idx, errs| "Record #{idx}: #{errs}" }.join("; ")
     raise Dami::ValidationError.new(message, all_errors)

data/lib/dami/schema/generator.rb

@@ -10,7 +10,7 @@ module Dami
 
         timestamp = Time.now.utc.strftime('%Y%m%d%H%M%S')
         
-        # THE FIX: This converts "AddEmailToUsers" into "add_email_to_users"
+        # "AddEmailToUsers" -> "add_email_to_users"
         snake_case_name = name.gsub(/::/, '/')
                               .gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2')
                               .gsub(/([a-z\d])([A-Z])/,'\1_\2')

data/lib/dami/schema/loader.rb

@@ -15,7 +15,7 @@ module Dami
       def load_from_path(path)
         return unless File.exist?(path)
         
-        # THE FIX: Capture `self` (the loader instance) into a variable.
+        # Capture `self` (the loader instance) into a variable.
         loader_instance = self
         
         # Now, the monkey-patched method uses the captured variable, ensuring

data/lib/dami/version.rb

@@ -1,3 +1,3 @@
 module Dami
-  VERSION = "1.0.0"
+  VERSION = "1.0.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dami
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Steven Garcia