Review: Ash core feature inventory

Review: ash-features (notes/research/01-ash-features.md)

Review of: Ash core feature inventory.

VERDICT: ACCEPT-WITH-FIXES

Reviewer: independent fact-check against scratch/ash-src/ash (3.33.11, mix.exs:13 @version "3.33.11").
All paths below are relative to scratch/ash-src/ash/ unless they start with notes/.

The verdict is revise and resubmit. The structure is good and most section and entity names are
right. But the document calls itself a “complete” inventory, and six of its “complete” lists have
the wrong count:

• changes, preparations, policy checks and mix tasks are each missing items;
• the expression function list is missing about 15 registered functions;
• the type list mixes in helper modules and a module name that does not exist.

Other problems:

• One headline claim is false: “no generators”. The generators guide that the document itself cites lists 8 ash.gen.* tasks.
• 4 of the 13 Summary bullets are wrong and 2 more are partly wrong.
• The density “derived” table contains derivations that are made up.
• 44% of sampled citations point at the wrong line, and 17% do not support the claim.

---

1. Error table

Line = line in notes/research/01-ash-features.md.

Tally: 9 high, 18 medium, 17 low.

---

2. Acceptance criteria

0 complete, 1 complete with a minor error, 12 partial, 0 missing.

---

3. Citation sample

70 citations checked across all 13 sections, the Summary and §13.

Most wrong-line citations into DSL-Ash.Resource.md are 1-4 lines off, all in the same direction. The researcher likely counted from table headers. Examples, each cited → actual:

• require_atomic? :1851 → :1854
• accept :1230 → :1228
• primary? :1225 → :1222
• manual? :1237 → :1236
• action_select :1231 → :1229
• touches_resources :1213 → :1225
• get_by :1509 → :1512
• read timeout :1510 → :1513
• soft? :2141 → :2145
• notifiers :1236 → :1235
• error_handler :1235 → :1234
• base_filter :2746 → :2749
• trace_name :2748 → :2751
• all_tenants? :2831 → :2828
• validate on :3031 → :3030
• manual :446 → :448
• through example :566 → :564
• many_to_many.through/join_relationship :675-676 → :678-679

In other files, cited → actual:

• DSL-Ash.Domain.md: authorization :447-449 → :451-452; timeout :418 → :422; trace_name :422 → :423; resources example :44-48 → :51-54.
• lib/ash.ex: can? :1838 → :1840; can :1956 → :1963; can_see_fields? :2056 → :2063; can_see_fields :2094 → :2101; can_do_all? :2161 → :2164; can_do_all :2203 → :2207.
• expressions.md: functions :65-88 → :69-91; upsert_conflict :88 → :91.
• policies.md: :120 → :122.
• mix.exs: :2 → :13.
• .formatter.exs: :3 → :5.

In get-started.md the drift is 7-40 lines:

• attribute :subject :250 → :177/:238
• constraints :246 → :253
• accept :262-264 → :271-273
• validate :322-325 → :325-327
• error output :308-311 → :304-308
• belongs_to :551-556 → :561-567
• ETS :436-440 → :476-479
• attribute block :224-250 → :236-261
• create :open :256-266 → :266-275
• assign :586-588 → :593-598

The 12 citations that do not support their claim:

• get-started.md:165 (four actions)
• DSL-Ash.Resource.md:1021-1034 (argument options)
• changeset.ex:4743
• DSL-Ash.Resource.md:1852-1854 (atomic_upgrade_with)
• authorizer.ex:260-280
• policies.md:119-121 (the update/destroy/create semantics are at :229-233)
• error.ex:30
• authorizer.ex:164-210
• error.ex:20-37
• get-started.md:569-573
• DSL-Ash.Resource.md:248 (generated?)
• DSL-Ash.Resource.md:933-940

Citations that do support, for the record:

• all 14 Resource and 4 Domain headings
• authorizer.ex:282, :222-224
• policies.md:124-149, :151-154, :157-178, :609-711
• all 21 built_in_checks.ex lines, and every change/builtins.ex and validation/builtins.ex line
• notifiers.md:31-70, :113
• generic-actions.md:258, :391
• the multitenancy and monitoring guide headings
• expressions.md:188-198
• DSL-Ash.Resource.md:2416-2480, :2612-2620, :2785-2833, :1709-1725, :4200-4245, :4334-4348, :4377-4388
• error.ex:53, :78-96
• changeset.ex:5066

---

4. Code examples

No example is invented. Six are trimmed without an ellipsis or note, which breaks rule 5’s “copied” requirement. The doc’s own claim at line 752 (“I have not silently merged in anything else”) holds, but it did silently remove lines.

---

5. Settled [unverified] claims and open questions

1. Callbacks of NewType, Struct, Union, Enum and Range.
   • Ash.Type.NewType declares subtype_of/0, lazy_init?/0, subtype_constraints/0 and type_constraints/2 (lib/ash/type/new_type.ex:39-45).
   • Ash.Type.Enum declares values/0, label/1, description/1, details/1, match?/1 and match/1 (lib/ash/type/enum.ex:142-155).
   • Union, Struct and Range declare no @callback. They are concrete types configured through constraints, not behaviours.
2. No-policy default. Once a resource uses Ash.Policy.Authorizer, a request that no policy applies to is forbidden.
   • raw_expression/1 folds the policies from {false, true} (lib/ash/policy/policy.ex:81).
   • It returns one_condition_matches and all_policies_match (:97).
   • So with zero applicable policies the expression is false.
   • A bypass counts toward “at least one applies” only if it authorizes (:85-86).
   • A resource without the authorizer has no policy authorization at all. The authorizer is opt-in through authorizers: [Ash.Policy.Authorizer] (policies.md:20).
3. Field-policy options.
   • field_policy takes fields (required, positional), an optional condition and description, plus the 4 check entities (authorizer.ex:335-367).
   • field_policy_bypass is the same with bypass?: true (:370-376).
   • Only filter or expression checks are allowed (DSL-Ash.Policy.Authorizer.md:813-845).
   • Forbidden fields become %Ash.ForbiddenField{}.
4. Pipelines. An action uses a pipeline through the pipe_through entity. Example: pipe_through [:change_state], where: …. Pipeline entities are prepended to the action’s own changes and preparations (DSL-Ash.Resource.md:1127-1160, and the section intro at :3049-3050).
5. Telemetry events. There are 18 events, each with :start/:stop suffixes (monitoring.md:17-44): [:ash, domain, :create|:update|:read|:destroy|:action|:bulk_create|:bulk_update|:bulk_destroy], plus [:ash, :changeset|:query|:validation|:change|:calculation|:before_action|:after_action|:preparation|:notifier|:request_step]. There are also 18 trace types (monitoring.md:75-92).
6. Generators. They exist in core. See the mix tasks row in §1 (lib/mix/tasks/gen/*.ex, generators.md:45-54).
7. Per-kind aggregate options (DSL-Ash.Resource.md:3296-4102).
   • Shared by all kinds: relationship_path, read_action, filter, description, default, public?, filterable?, sortable?, sensitive?, authorize?, multitenancy.
   • field on every kind except count and exists.
   • uniq? on count and list.
   • include_nil? on first and list.
   • sort on first, list and custom.
   • type and implementation on custom.
   • join_filter takes relationship_path, filter (:3356-3398).
8. Open question 8 (“no web sources needed”) is fine as a statement.

---

6. List recounts

---

7. Omissions (user-facing features absent from the document)

Compared against DSL-Ash.Resource.md, DSL-Ash.Domain.md, DSL-Ash.Policy.Authorizer.md and documentation/topics/:

1. Built-in data layers. Ash.DataLayer.Ets, Ash.DataLayer.Mnesia and Ash.DataLayer.Simple ship in core (lib/ash/data_layer/{ets,mnesia,simple}, documentation/dsls/DSL-Ash.DataLayer.Ets.md, DSL-Ash.DataLayer.Mnesia.md). The use Ash.Resource options (data_layer, authorizers, notifiers, simple_notifiers, extensions, domain) are never listed.
2. Policy access types. access_type (:strict/:filter/:runtime) and default_access_type are missing (policies.md:227-269). They decide filter-versus-error behaviour, which is central to criterion 6.
3. Policy error_message (policies.md:370-447), policy breakdowns and logging (:967-1047), can_read/accessing_from composition (:516-579) and authorize_read_with / allow_forbidden_field? on relationships (:467-515).
4. Actors and Ash.Scope (documentation/topics/security/actors-and-authorization.md, multitenancy.md:51, lib/ash/scope.ex). The actor:, tenant:, authorize?: and scope: call options are never explained.
5. Sensitive data guide (documentation/topics/security/sensitive-data.md). Only the sensitive? flag appears.
6. Ash.Reactor in core (documentation/dsls/DSL-Ash.Reactor.md, documentation/topics/advanced/reactor.md, multi-step-actions.md). A one-line pointer to ash-ecosystem is enough, but it is core.
7. Ash.TypedStruct DSL (documentation/dsls/DSL-Ash.TypedStruct.md).
8. Custom change, validation and preparation behaviours (Ash.Resource.Change, Ash.Resource.Validation, Ash.Resource.Preparation). Their callbacks (change/3, atomic/3, batch_change/3, validate/3, prepare/3) are how users extend actions (documentation/topics/resources/changes.md, validations.md, preparations.md).
9. Custom expressions (Ash.CustomExpression, expressions.md:200-215) and calculation arguments and module callbacks (documentation/topics/resources/calculations.md).
10. Bulk action strategies and options (:atomic, :atomic_batches, :stream, return_records?, notify?), found in lib/ash.ex bulk_update_opts (:609) and the update-action guide.
11. Testing support: Ash.Generator, Ash.Seed, Ash.Test (lib/ash/generator/generator.ex, lib/ash/seed.ex, lib/ash/test.ex, documentation/topics/development/testing.md).
12. Timeouts guide (documentation/topics/advanced/timeouts.md), temporal resources guide (documentation/topics/advanced/temporal-resources.md; only the option list is given) and combination queries (documentation/topics/advanced/combination-queries.md).
13. Introspection modules Ash.Resource.Info and Ash.Domain.Info. Every DSL entity documents an “Introspection” target.
14. usage-rules.md and usage-rules/ (14 files) shipped in the ash repo. These are LLM rules, directly relevant to mesh’s agent-legibility goal.
15. How-to guides in documentation/how-to/: polymorphic relationships, encrypt attributes, prevent concurrent writes (optimistic_lock), wrap external APIs.

---

Round 2 re-verification

Re-checked the revised notes/research/01-ash-features.md (1,211 lines, ends with ## Revision log (round 2)) against source again.

Verdict: ACCEPT-WITH-FIXES.

• Every high finding from round 1 is fixed correctly.
• All seven corrected counts now match source.
• What is left: 7 medium issues, most of them new errors in the text added this round, and a set of low issues (line drift and two counts).
• None of them needs restructuring.

R2.1 Reviewer corrections: errors in my own round-1 review

The researcher copied two of these into the document, so both sides need to fix them.

• field is an option on count. I wrote “field on every kind except count and exists”. In fact count has field (DSL-Ash.Resource.md:3344). Correct statement: field is on every kind except exists.
• registry.ex line numbers. I gave wrong line numbers for the short names. The correct ones are: file :16, function :19, struct :21, union :36, range :39, and @custom_short_names :44.

R2.2 Status of round-1 high and medium findings

All of the following are now correct in the document, checked against source:

• 14 sections.
• The changes and preparations purposes, quoted at :2842 and :2914.
• Built-in counts: 24 changes, 24 validations, 4 preparations and 22 checks. The macro lines (102, 466, 496, 523, 550; 57, 82; 422) match.
• 5 templates, with ^tenant at expr.ex:106.
• 39 functions (filter.ex:76-116).
• 91 error leaf modules.
• Splode, at error.ex:9-18.
• 25 mix tasks.
• The Summary now agrees with §13.
• Argument options (:1025-1030).
• bypass has all four check entities.
• The 31 types; Ash.TypedStruct.
• PK and timestamp options (:212-224, :262-268, :309-315).
• The relationship matrix: which kind has which option is now right.
• defaults (:937).
• atomic_upgrade? (:1855).
• The four policy options (authorizer.ex:166-202).
• No-policy default (policy.ex:81,97).
• can? citation.
• The Ash.Query list.
• The density “derived” rows and the “3 of 14” statement.
• §13 rows 4 and 11.

Low findings, sampled 9 of 17. Fixed: public? :98, the atomic/3 sentence, the Ash.Error.Changes.InvalidAttribute name, ash.generate_policy_charts, and the plan “6 blocks / 5 sections”. Still wrong: the registry lines (see R2.4), the get-started.md query citation (see R2.4), and the word count (see R2.4).

R2.3 Still wrong: medium (fix before acceptance)

R2.4 Still wrong: low

Wrong line numbers. The claims are true; only the line is wrong.

Copy fidelity and wrong facts.

• Line 35: “16 operators”. Registered operator modules are 15: 8 at filter.ex:120-129 plus the 7 symbols in basic.ex (+ * - / <> || &&). and/or are boolean expressions, not operator modules. Say “15 registered operators; the guide lists 15 + is_nil”.
• Line 909: “4 executable how-to guides”. documentation/how-to/ has 7 .livemd files.
• Line 644-646: Ash.Scope “bundles actor + authorize? + tenant + context into one value that every Ash.* call accepts”. The source says a user struct implements the Ash.Scope.ToOpts protocol so that actor, tenant, context, authorize? and tracer can be pulled out of it (lib/ash/scope.ex:5-12 and the “Passing scope and options” section). The cited multitenancy.md:51-64 does not say “every call”.
• Lines 560-578 and 785-790: the “verbatim” policy and pub_sub examples each drop one blank line (policies.md:168, DSL-Ash.Notifier.PubSub.md:137). The policy citation :161-174 should be :159-178.
• Line 982: the tutorial’s attributes do and ... lines (get-started.md:236-237) are merged onto one line.
• Line 1210: “~5,900 words”. wc -w gives 8,419. Either cut the document or report the real number.

R2.5 Recounts against source

R2.6 Fresh citation sample (30 not checked in round 1)

Supports:

• lib/ash/resource.ex:20-60, :25
• DSL-Ash.Resource.md:938, :988
• lib/ash.ex:3880, :578/:639
• changeset.ex:5697-5734, :6136, :813
• authorizer.ex:325-331, :186-200
• policy.ex:81,97
• basic.ex:9-10
• get-started.md:503-505
• DSL-Ash.Notifier.PubSub.md:135-141
• monitoring.md:17-44
• ash.generate_policy_chart.ex:5

Wrong line, claim true:

• DSL-Ash.Resource.md:936
• registry short-name lines
• registry.ex:41
• embedded-resources.md:78
• the multitenancy option lines
• DSL-Ash.Resource.md:2150
• :1862/:2163
• authorizer.ex:389-395
• expr.ex:103-112
• the relationship-matrix lines

Does not support:

• DSL-Ash.Resource.md:3049-3050: the quoted text is not there.
• policies.md:246-269: those lines are about :runtime, not :filter/create.
• get-started.md:411/:414: not the cited code.

Outside the sample but invented: Ash.for_action/4 and Calculation.batch/2 (both in R2.3).

R2.7 The 15 omissions

R2.8 The [unverified] claims, settled

1. Splode field list. Every error is a defexception with its own fields plus splode: nil, bread_crumbs: [], vars: [], path: [], stacktrace: nil, class: (scratch/ash-src/splode/lib/splode/error.ex:112-120). The reserved names are listed at :94. Error classes also add errors: [] (splode/lib/splode/error_class.ex:11). Version: splode 0.3.2 (splode/mix.exs:8), the version pinned by ash’s mix.lock:53.
2. GenServer usage.
   • Ash.DataLayer.Ets.TableManager uses GenServer (lib/ash/data_layer/ets/ets.ex:76-78, started at :101).
   • Ash.TypeResolver uses GenServer (lib/ash/type_resolver.ex:7, started at :17).
   • lib/ash/actions/read/async_limiter.ex:16 uses an Agent.
   • Replace the [unverified] on lines 11-12 and open question 3 with these.
3. A denser real example exists. See R2.9. Remove “no official example uses most sections” (lines 950-953) and open question 2, or qualify the claim as “in the ash clone”.

R2.9 Dense real resource for §12

Pick: Tunez.Music.Album. It comes from the Ash book’s sample app (Rebecca Le, sevenseacat/tunez).

• URL: https://github.com/sevenseacat/tunez/blob/end-of-chapter-10/lib/tunez/music/album.ex
• Branch end-of-chapter-10, commit 5ea6daeac0d8634bca22cddd3fc7331f6391f3c3 (2026-01-11).
• mix.lock pins ash 3.12.0.
• 146 lines.
• The main branch is the starter app and has no album.ex, so cite the branch.

What it uses:

• 8 of the 14 Ash.Resource sections:
  • actions: defaults [:read], create, update with require_atomic? false, destroy, an argument, and the manage_relationship and cascade_destroy changes.
  • changes: a custom change plus relate_actor with on:.
  • validations: numericality and match, with where: and message:.
  • attributes: including create_timestamp and update_timestamp.
  • relationships: belongs_to and has_many with sort.
  • calculations: one module-based and one expr using ^actor.
  • aggregates: sum.
  • identities: with message:.
• policies (from the authorizer extension): bypass, action, action_type and an expr check.
• 3 extension sections: graphql, json_api and postgres.
• The code interface is declared on the domain, not the resource. lib/tunez/music.ex:68-73 on the same branch has define :create_album, :get_album_by_id (get_by: :id), :update_album and :destroy_album. Cite both files.

Excerpt (lines 27-66, verbatim, 40 lines):

  actions do
    defaults [:read]

    create :create do
      accept [:name, :year_released, :cover_image_url, :artist_id]
      argument :tracks, {:array, :map}
      change manage_relationship(:tracks, type: :direct_control, order_is_key: :order)
    end

    update :update do
      accept [:name, :year_released, :cover_image_url]
      require_atomic? false
      argument :tracks, {:array, :map}
      change manage_relationship(:tracks, type: :direct_control, order_is_key: :order)
    end

    destroy :destroy do
      primary? true

      change cascade_destroy(:notifications, return_notifications?: true, after_action?: false)
    end
  end

  policies do
    bypass actor_attribute_equals(:role, :admin) do
      authorize_if always()
    end

    policy action(:create) do
      authorize_if actor_attribute_equals(:role, :editor)
    end

    policy action_type([:update, :destroy]) do
      authorize_if expr(can_manage_album?)
    end

    policy action_type(:read) do
      authorize_if always()
    end
  end

Runner-up in the Ash clone: scratch/ash-src/ash/test/support/policy_complex/resources/post.ex (120 lines). It uses 7 of the 12 section keywords checked, but it is test scaffolding, not a documented example.

Note for the researcher: Tunez is pinned to ash 3.12.0, while the clone is 3.33.11. Say so when citing it (rule 3).

---

Round 3 final check

This is the final check of notes/research/01-ash-features.md after round 3: 1,484 lines and 10,020 words by wc -w. All findings were re-verified against scratch/ash-src/ash 3.33.11, scratch/ash-src/splode 0.3.2, and the Tunez file fetched with gh api at commit 5ea6daeac0d8634bca22cddd3fc7331f6391f3c3.

Final verdict: ACCEPT-WITH-FIXES.

• The document is reliable if readers apply the 16 errata in “Residual errors” below.
• There are no high or medium factual errors left in the inventory.
• What remains:
  • 6 wrong function arities in §8.3 and §3.4/§5;
  • 2 @doc false functions listed as public, and 5 public functions missing, in §8.2;
  • 2 wrong line numbers;
  • 1 unmarked omission in the Tunez quote;
  • 2 inaccurate statements in the analysis section.

R3.1 Status of the round-2 “still wrong” items

R3.2 API existence sweep (§4, §6, §8)

I checked every function, callback, module and option name in these sections against def/defmacro/@callback/defmodule/defprotocol and the DSL option tables, including arity and default arguments. Everything exists except the items numbered #2, #4-#5 and #9-#13 under “Residual errors”. Names confirmed in this sweep that were never checked in earlier rounds:

• Ash.Resource.Actions.Implementation (lib/ash/resource/actions/action/implementation.ex:5)
• Ash.Scope.ToOpts (lib/ash/scope.ex:127, nested defprotocol)
• Ash.ForbiddenField (lib/ash/forbidden_field.ex:5)
• Ash.Error.Forbidden.Policy (lib/ash/error/forbidden/policy.ex:5)
• Ash.PlugHelpers.set_tenant/2 (lib/ash/plug_helpers.ex:134)
• SimpleCheck match?/3 (simple_check.ex:43) and Check describe/1 (check.ex:76)
• FilterCheck filter/3 (filter_check.ex:43)
• Ash.Changeset.handle_errors/2 (:7818) and Ash.ActionInput.handle_errors/2 (action_input.ex:1034)
• the six changeset hook functions (changeset.ex:7326-7731, /2 with optional opts)
• with_hooks/3 (:4743)
• the runners run_before_transaction_hooks/1, run_before_actions/1, run_after_transactions/2, run_after_actions/3
• fully_atomic_changeset/4
• bulk_create/3, bulk_update/4, bulk_destroy/4 (arities valid with defaults)
• can_see_fields?/4, can_do_all?/2
• transact/3, transaction/3
• the authorize_with option (lib/ash.ex:152, :298)

R3.3 §12.1 Tunez.Music.Album

• I fetched the file at the cited commit. It is byte-identical to the end-of-chapter-10 branch (146 lines).
• The quote is verbatim except for the marked omissions (json_api, postgres, validations, two attribute blocks) and one unmarked omission: def next_year, do: Date.utc_today().year + 1 (album.ex:88). This contradicts “and nothing else” at doc lines 1156-1158 (residual #14).
• lib/tunez/music.ex:68-73 at that commit matches the quote exactly.
• “8 of the 14 sections” is correct.
• Derivation table, all 10 rows supported:
  • uuid_primary_key → DSL-Ash.Resource.md:262-268
  • timestamps Ash.Type.UTCDatetimeUsec → :125-131, :166-174
  • define_attribute? default true → :787
  • :direct_control = on_lookup: :ignore, on_no_match: :create, on_match: :update, on_missing: :destroy, matching “diff against existing” → changeset.ex:5734-5741
  • relate_actor → builtins.ex:34
  • cascade_destroy → :407
  • identity → :2785-2833
  • sum/field → :3616
  • the calculation is used by the policy, as visible in the quote
  • the domain define has a functions option, default all five → DSL-Ash.Domain.md:147

R3.4 §8.2 compared with changeset.ex

I classified every top-level def in lib/ash/changeset/changeset.ex as public or @doc false. There are 71 public functions.

• Listed but @doc false: atomic_condition (@doc false at :1732) and temporal_recorded_at (@doc false at :4304).
• Public but missing: apply_attributes (:7758), fetch_argument_or_attribute (:5544), force_change_new_attribute (:6896), force_change_new_attribute_lazy (:6910), force_delete_argument (:6862).
• Wrong line numbers: fetch_argument_or_change is cited at :5544 but is at :5559 (:5544 is fetch_argument_or_attribute); filter is cited at :7836 but is at :7832.
• Every other listed function is public and its line number is correct. The list of @doc false internals at doc lines 767-773 is correct.

R3.5 Fresh citation sample (25 not checked in earlier rounds)

Supports:

• DSL-Ash.Resource.md:1233, :1515, :1222-1227, :989-994, :1509-1521, :1134, :787, :3616
• change/builtins.ex:517-522, :460-464, :544/:487, and preparation/builtins.ex:51/:76
• validation.ex:69,77,99
• calculation.ex:209-222
• custom_expression.ex:71-101
• manual_relationship.ex:35-37
• action_input.ex:253
• scope.ex:5-12, :55-61
• splode/lib/splode/error.ex:112-120, :94
• ets.ex:76-78, :101
• DSL-Ash.Domain.md:107-291 (functions at :147)
• tunez music.ex:68-73

Wrong line, claim true: changeset.ex:5544 (fetch_argument_or_change), :7836 (filter).

Does not support: changeset.ex:1743 and :4307, cited as public functions when both are @doc false.

R3.6 Did round 3 break anything?

No regressions found. Every section that was correct after round 2 is still present, with the same facts:

• §1, §2.1-2.4, §3, §4.2-4.5, §4.7-4.13, §5, §6, §7, §9, §10, §11.1-11.6, §12 Ticket, §13.

Round 3 deleted only these:

• the round-2 open questions it settled: Splode, GenServer and the dense example;
• the “generic only” error_handler line, which was moved to the correct list.

Residual errors (for readers)

Read the document with these corrections. Doc line numbers refer to the round-3 file.

Non-factual issue: the document is 10,020 words, above the 3,000-6,000 target in _rules.md. The document reports this honestly at line 1449.