Ash core feature inventory

01 — Ash core feature inventory (ash 3.x)

Independent fact-check: review of this document.

Version examined: ash 3.33.11 (scratch/ash-src/ash/mix.exs:13, @version "3.33.11").
All line references are to that shallow clone. One external source was used: the Tunez sample
app on GitHub for the dense example in §12 (cited there with branch and commit). Every other claim
is a local path with a line number.

Audience: a senior TypeScript engineer who has never used Elixir. Terms used once and then
assumed: macro (a compile-time function that generates code from its arguments; the DSL is built
from them); behaviour (Elixir’s “interface”: a named list of callbacks a module must implement);
changeset (a struct holding pending changes, arguments and errors for one write action);
GenServer (an OTP process holding state behind messages). GenServer usage in core: the ETS data
layer’s TableManager (lib/ash/data_layer/ets/ets.ex:76-78, started at :101) and
Ash.TypeResolver (lib/ash/type_resolver.ex:7, started at :17); the read action’s async
limiter uses an Agent (lib/ash/actions/read/async_limiter.ex:16).

Every DSL entity in the shipped references documents an “Introspection” target
(documentation/dsls/DSL-Ash.Resource.md), which the user reads at runtime through
Ash.Resource.Info and Ash.Domain.Info.

---

Summary

• A resource is one module, use Ash.Resource. Its whole surface is the DSL in
  documentation/dsls/DSL-Ash.Resource.md (4391 lines): 14 top-level sections —
  attributes, relationships, actions, code_interface, resource, identities, changes,
  preparations, validations, pipelines, aggregates, calculations, multitenancy,
  temporal (## headings at lines 8, 342, 854, 2403, 2726, 2765, 2841, 2913, 2976, 3048, 3253,
  4147, 4310, 4349). resource holds only options, no entities. Ash.Domain has 4:
  domain, resources, execution, authorization (DSL-Ash.Domain.md:8,37,402,430).
• Policies are not in DSL-Ash.Resource.md; they are a separate DSL extension
  (lib/ash/policy/authorizer/authorizer.ex:282) with 2 sections: policies, field_policies.
• 31 built-in types (lib/ash/type/registry.ex:8-40), plus the {:array, t} composite.
• 24 built-in changes (19 functions + 5 defmacros), 24 validations, 4 preparations (2 + 2),
  22 policy checks (21 + 1). grep -c ' def ' undercounts: it misses defmacro.
• 5 expression templates: ^actor, ^tenant, ^arg, ^context, ^ref (lib/ash/expr/expr.ex:103-131).
  39 registered expression functions (lib/ash/filter/filter.ex:76-116), 15 registered operators
  (the guide lists 15 + is_nil).
• Updates and soft destroys are atomic by default: require_atomic? defaults to true
  (documentation/dsls/DSL-Ash.Resource.md:1854).
• Multitenancy has 2 strategies (:context, :attribute) and 4 per-action override values
  (:enforce | :allow_global | :bypass | :bypass_all).
• Errors are built on Splode; 4 classes, 91 leaf modules.
• 25 mix tasks ship in core, including 9 ash.gen.* generators plus ash.install and
  ash.patch.extend; the repo also ships usage-rules.md and usage-rules/ (14 files of
  LLM-facing rules).
• Against the Mesh plan: it names attributes, relationships, actions (incl. generic), policies,
  calculations, aggregates, expr, domains, notifiers and multitenancy. It does not name
  identities, code interfaces, embedded resources, NewType, field policies, upserts, bulk
  actions or the error class hierarchy.

---

1. Resource anatomy

1.1 Ash.Resource — every DSL section

changes and preparations are not named/reusable — a change entity there is a change applied
to every create/update/destroy. Naming and reuse is what pipelines is for: “Pipeline entities are
prepended before the action’s own changes/preparations.” (:1134), attached with the
pipe_through entity (:1127-1160).

use Ash.Resource options (lib/ash/resource.ex:20-60): data_layer (default Ash.DataLayer.Simple, :25),
extensions (default [Ash.Resource.Dsl], :26), authorizers, notifiers,
simple_notifiers (:34), domain (:49), validate_domain_inclusion? (default true),
primary_read_warning?, embed_nil_values? (default true).

1.2 Action sub-sections

actions section options (:935-940):

• defaults — “Creates a simple action of each specified type, with the same name as the type. These
  will be primary? unless one already exists for that type.” So defaults [:read] creates only
  :read (:937).
• default_accept — default value for accept on each action; “Ash >= 3.0 defaults to no
  attributes accepted” (:938).

1.3 Ash.Domain

resources do
  resource MyApp.Tweet
  resource MyApp.Comment
end

(verbatim, documentation/dsls/DSL-Ash.Domain.md:52-55)

1.4 Policies DSL (separate extension)

documentation/dsls/DSL-Ash.Policy.Authorizer.md, ## headings at lines 35 and 813:

• policies → policy (98), policy_group (322), bypass (612). Section option
  default_access_type (:strict | :filter | :runtime, default :filter;
  lib/ash/policy/authorizer/authorizer.ex:325-331).
• policy → authorize_if (155), forbid_if (195), authorize_unless (235), forbid_unless (275).
• policy_group → policy (381), which has the same four check entities (438, 478, 518, 558).
• bypass → all four: authorize_if (643), forbid_if (683), authorize_unless (723),
  forbid_unless (763).
• field_policies → field_policy, field_policy_bypass
  (lib/ash/policy/authorizer/authorizer.ex:335-376).

---

2. Attributes and types

2.1 Built-in types

The authoritative list is the 31 short names in @builtin_short_names
(lib/ash/type/registry.ex:8-40):

map, keyword, term, atom, tuple, string, integer, file, float, duration_name,
function, boolean, struct, uuid, uuid_v7, binary, date, time, time_usec,
decimal, ci_string, naive_datetime, utc_datetime, utc_datetime_usec, datetime,
duration, url_encoded_binary, union, module, vector, range.

:array is a composite usable with any type ({:array, MyApp.Profile},
documentation/topics/resources/embedded-resources.md:81). The same file also lists
@custom_short_names Application.compile_env(:ash, :custom_types, []) (:44), so apps can
register their own.

lib/ash/type/ also contains files that are not types: comparable.ex,
composite_type_helpers.ex, helpers.ex, registry.ex, type.ex (the behaviour module).
enum.ex and new_type.ex are macro/behaviour modules for defining your own types.

:struct, :union, :range, :file and :function are plain atom short names
(registry.ex:21, :36, :39, :16, :19) and are configured through constraints, not callbacks.

• Ash.Type.NewType declares subtype_of/0, lazy_init?/0, subtype_constraints/0,
  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,
  match/1 (lib/ash/type/enum.ex:142-155).
• Ash.Type.Union, Ash.Type.Struct and Ash.Type.Range declare no @callback.

For structs there is also Ash.TypedStruct (lib/ash/typed_struct.ex:5,
documentation/dsls/DSL-Ash.TypedStruct.md) — there is no Ash.Type.TypedStruct.

2.2 attribute options

Full list of 16, documentation/dsls/DSL-Ash.Resource.md:86-107:

2.3 Timestamps and primary keys

attributes has five convenience entities: create_timestamp (113), update_timestamp (157),
integer_primary_key (202), uuid_primary_key (248), uuid_v7_primary_key (292). They expand into
ordinary attribute entries, but the options differ:

2.4 Constraints, custom types, embedded resources

• Constraints are per-type keyword lists passed to the type at cast time. Tutorial usage:
  constraints [one_of: [:open, :closed]] on an :atom (documentation/tutorials/get-started.md:253).
• Embedded resources are use Ash.Resource, data_layer: :embedded
  (documentation/topics/resources/embedded-resources.md:52-59). Because an embedded resource
  defines an Ash.Type under the hood, it can be used anywhere a type can
  (:71-78). The guide warns embedded resources cannot have aggregates or data-layer-specific
  expression calculations (:61-64).

2.5 Custom change / validation / preparation behaviours

---

3. Relationships

Kinds: has_one (:405), has_many (:517), many_to_many (:630), belongs_to (:743).
Each accepts a nested filter entity.

3.1 Options — the four lists are NOT identical

3.2 Manual relationships

manual takes a module implementing Ash.Resource.ManualRelationship or a 2-arg function
(source_records, context); setting it implies no_attributes? true
(documentation/dsls/DSL-Ash.Resource.md:448).

3.3 through / many-to-many

through on has_one/has_many is a list of relationship names to traverse:
“for example, through: [:classrooms, :teachers] would load all teachers from all classrooms”
(:564). For many_to_many, through names the join resource and join_relationship names
the has_many to it, defaulting to <relationship_name>_join_assoc (:678-679).

3.4 Managing relationships from actions

Built-in change manage_relationship(argument, relationship_name \\ nil, opts)
(lib/ash/resource/change/builtins.ex:305). Its @doc (:290-296) gives the two forms:

change manage_relationship(:comments, type: :append)
change manage_relationship(:remove_comments, :comments, type: :remove)

The type: values are :append_and_remove, :append, :remove, :create, :direct_control
(lib/ash/changeset/changeset.ex:5697, :5707, :5717, :5726, :5734). On the changeset:
manage_relationship/4 (:6136), manage_relationship_opts/1 (:5697-5743),
manage_relationship_schema/0 (an @doc false schema constant, :6010). Related built-ins: cascade_destroy
(lib/ash/resource/change/builtins.ex:407) and cascade_update (:447).

---

4. Actions

4.1 The five action types

create (1178), read (1471), update (1820), destroy (2107), generic action (942).

defaults names which standard actions to generate, each with the same name as its type
(:937). Tutorial usage: defaults [:read] creates only :read — “Use the default implementation
of the :read action” (documentation/tutorials/get-started.md:164-165).

Shared by create/update/destroy only (read and generic action lack them): accept (:1228,
:1864, :2157), action_select (:1229), require_attributes, allow_nil_input,
delay_global_validations?, notifiers (:1235), manual? (:1236).

Shared by create/read/update/destroy but not generic action: multitenancy (:1220,
:1514, :1857, :2147) and skip_global_validations? (:1233, :1515).

Shared by create, update, destroy and generic action — not read: error_handler, “Sets the
error handler on the changeset” (:1234) or “on the action input” (:988).

Shared by all five (:1222-1227, :989-994): primary? (:1222), description,
transaction? (reads default false, writes true when supported), touches_resources (:1225),
skip_unknown_inputs, public?.

Read’s full option list (:1509-1521): manual, get?, modify_query, get_by, timeout,
multitenancy, skip_global_validations?, primary?, description, transaction?,
touches_resources, skip_unknown_inputs, public?. Read has none of accept, action_select,
require_attributes, allow_nil_input, delay_global_validations?, notifiers, manual? or
error_handler.

Generic action only (:985-994): returns (positional), constraints, allow_nil?
(default false), run (an Ash.Resource.Actions.Implementation module or a Reactor).

• accept — “the list of attributes to accept. Use :* to accept all public attributes” (:1228).
  Tutorial: create :open do accept [:subject] end (documentation/tutorials/get-started.md:271-273).
• action_select — “controls which attributes are present (vs %Ash.NotLoaded{}) on the record
  passed to after_action hooks, notifiers, and returned to the caller” (:1229).
• Read-specific: manual, get?, modify_query, get_by (:1512 — “sets get?
  to true, add args for each of the specified fields, and adds a filter for each of the arguments”),
  timeout (:1513).

4.2 Arguments

argument name, type (:1019) — type is a positional argument, not an option. Options are
description, constraints, allow_nil?, public?, sensitive?, default (:1025-1030).
There is no doc option.

4.3 Built-in changes (complete, 24)

lib/ash/resource/change/builtins.ex — 19 functions + 5 macros:

filter (18), relate_actor (34), debug_log (44), optimistic_lock (53),
get_and_lock_for_update (74), get_and_lock (92), update_change macro (102), increment
(122), set_attribute (156), atomic_set (206), atomic_update (247), set_new_attribute (267),
prevent_change (283), manage_relationship (305), set_context (325), load (338), select
(357), ensure_selected (371), cascade_destroy (407), cascade_update (447),
after_action macro (466), after_transaction macro (496),
before_action macro (523), before_transaction macro (550).

4.4 Built-in validations (complete, 24)

lib/ash/resource/validation/builtins.ex: one_of (22), data_one_of (34), changing (52),
confirm (66), attribute_does_not_equal (81), negate (93), any (108), all (129),
action_is (143), attribute_equals (158), attribute_in (175), string_length (193),
byte_size (211), numericality (233), compare (239), match (253), present (282),
attributes_present (301), absent (337), attributes_absent (375),
argument_does_not_equal (415), argument_equals (430), argument_in (445),
pre_flight_authorization (463).

validate attribute_does_not_equal(:status, :closed) do
  message "Ticket is already closed"
end

(verbatim, documentation/tutorials/get-started.md:325-327)

4.5 Built-in preparations (complete, 4)

lib/ash/resource/preparation/builtins.ex: set_context (21), build (39),
before_action macro (57), after_action macro (82). Preparations take no action-input
arguments — they rewrite a query.

4.6 Lifecycle hooks

The DSL-level way users attach them — these are the 6 macros in §4.3/§4.5, written inside a
change or prepare entity. Two of the six, verbatim from the macro docs — note the arities:
before_action gets (changeset, context), after_action also gets the record:

change before_action(fn changeset, _context ->
  Logger.debug("About to execute #{changeset.action.name} on #{inspect(changeset.resource)}")

  changeset
end)

(verbatim, lib/ash/resource/change/builtins.ex:517-522)

change after_action(fn changeset, record, _context ->
  Logger.debug("Successfully executed action #{changeset.action.name} on #{inspect(changeset.resource)}")
  {:ok, record}
end)

(verbatim, lib/ash/resource/change/builtins.ex:460-464)

The other four heads (verbatim, one line each): change before_transaction(fn changeset, _context ->
(lib/ash/resource/change/builtins.ex:544), change after_transaction(fn (:487),
prepare before_action(fn query, _context -> (lib/ash/resource/preparation/builtins.ex:51),
prepare after_action(fn query, records, _context -> (:76).

On Ash.Changeset the imperative equivalents are before_transaction/2,
around_transaction/2, after_transaction/2, before_action/2, around_action/2,
after_action/2; the runners are run_before_transaction_hooks/1 (:5066),
run_before_actions/1 (:5115), run_after_transactions/2 (:5205),
run_after_actions/3 (:5308). with_hooks/3 is the wrapper (:4743).

Ash.Query has no around_action. Generic actions have a dedicated “Action Hooks” section
(documentation/topics/actions/generic-actions.md:258) and an “Execution Order” section (:391).

4.7 Upserts

Create-action options: upsert?, upsert_identity, upsert_fields
(:replace_all | {:replace, …} | {:replace_all_except, …} | atom | list(atom)),
upsert_condition, return_skipped_upsert? (:1214-1219). The upsert_conflict/1 expression
function refers to the incoming value during an upsert
(documentation/topics/reference/expressions.md:91).

4.8 Bulk actions

Ash.bulk_create/3, Ash.bulk_update/4, Ash.bulk_destroy/4 plus bang variants.
Strategies: “:strategy - One or more of :atomic, :atomic_batches, and :stream” (lib/ash.ex:3880);
“:stream is used in all cases if the data layer does not support atomics” (:578, :639). Other
shared bulk options: return_records?, notify?, stream_batch_size, allow_stream_with
(:keyset | :offset | :full_read, :555, :625). Filter checks apply to the reads bulk update and
destroy generate (policies.md:122).

4.9 Atomic updates and require_atomic?

update and destroy both default require_atomic? true (:1854, :2148). “This means that all
changes and validations implement the atomic callback” (:1854). atomic_upgrade? (default
false) is the option that is “Ignored if required_atomic? is true” (:1855);
atomic_upgrade_with is the read action used when upgrading (:1856). Atomic built-ins:
atomic_set (lib/ash/resource/change/builtins.ex:206), atomic_update (:247), plus
increment (:122) and optimistic_lock (:53). Among the atomic-execution helpers named here,
fully_atomic_changeset/4 (:813) is the only public one. Other public atomic functions are atomic_defaults (:895), atomic_ref (:1703),
atomic_update (:2417) and atomic_set (:2607); run_atomic_change/3 (:1300),
run_atomic_validation/3 (:1217), add_atomic_validations/3 (:3985) and
apply_atomic_constraints/3 (:3880) are @doc false internals.

4.10 Manual actions

manual on read/create/update/destroy accepts a module, {module, opts} or a function
(:1509, :1853, :2146); manual? true skips the data-layer call (:1236). Guide:
documentation/topics/actions/manual-actions.md.

4.11 Pagination

actions.read.pagination (:1698-1727), 9 options: keyset? (default false), offset?
(default false), via_data_layer? (default :data_layer_default), default_limit, countable
(default true), max_page_size (default 250), stable_sort (defaults to the primary key),
required?, paginate_by_default?. Runtime: Ash.get, Ash.get!, Ash.first, Ash.list,
Ash.page, Ash.count, Ash.load (lib/ash.ex). Guide:
documentation/topics/advanced/pagination.livemd.

4.12 Transactions

transaction? on every action type and touches_resources (:1225) “used when building
transactions”. Ash.transact/3 and Ash.transaction/3 (lib/ash.ex). Notifiers only fire after
commit (documentation/topics/resources/notifiers.md:113).

4.13 Soft destroy

destroy has soft? — “If specified, the destroy action behaves as an update internally”
(:2145) — and its require_atomic? is “Only relevant if soft? is set to true” (:2148).

---

5. Query features

Ash.Query public functions (lib/ash/query/query.ex): filter_input, sort_input, do_filter,
filter, sort, select, deselect, selecting?, ensure_selected, distinct, distinct_sort,
limit, offset, page, default_sort, load, load_through, loading?, unload,
merge_query_load, calculate, load_calculation_as, aggregate, lock, set_actor,
set_argument, set_arguments, get_argument, fetch_argument, delete_argument, set_context,
put_context, set_tenant, set_domain, set_authorize?, set_tracer, as_of, for_read,
for_read_opts, authorize_results, add_error, set_result, clear_result, unset,
equivalent_to?, subset_of?, superset_of?, before_action, after_action,
before_transaction, around_transaction, after_transaction, build, data_layer_query,
new, apply_to, combination_of, combination_hydration_context, timeout, validate_load,
validate_calculation_arguments.

Helpdesk.Support.Ticket
|> Ash.Query.filter(contains(subject, "2"))
|> Ash.read!()

(verbatim, documentation/tutorials/get-started.md:503-505)

Combination queries (union, intersect, except, combine, left_join) are described in
documentation/topics/advanced/combination-queries.md and exposed on Ash.Query as
combination_of/2 and combination_hydration_context/1 (lib/ash/query/query.ex:564).

5.1 Calculations

Expression-based or module-based, with load: for required fields (:4200-4214). Options (:4230-4245):
async?, constraints, description, public?, sensitive?, load, allow_nil?, filterable?,
sortable?, field?, multitenancy. Calculations can take their own argument entities (:4247).

calculate :full_name, :string, expr(first_name <> " " <> last_name)

(verbatim, documentation/dsls/DSL-Ash.Resource.md:4204)

5.2 Aggregates

9 kinds. Options shared by all kinds (:3296-4102): relationship_path, read_action,
filter, description, default, public?, filterable?, sortable?, sensitive?,
authorize?, multitenancy.

join_filter takes relationship_path and filter (:3356-3398).

aggregates do
  count :assigned_ticket_count, :reported_tickets do
    filter [active: true]
  end
end

(verbatim, documentation/dsls/DSL-Ash.Resource.md:3285-3289)

5.3 Expression operators

documentation/topics/reference/expressions.md:34-49 lists 15 operators plus is_nil. The
registered operator modules are also 15: the 8 named at lib/ash/filter/filter.ex:120-129
(IsNil, Eq, NotEq, In, LessThan, GreaterThan, LessThanOrEqual, GreaterThanOrEqual) plus the 7
symbols of Ash.Query.Operator.Basic (+ * - / <> || &&, lib/ash/query/operator/basic.ex:9-10),
registered through Ash.Query.Operator.Basic.operator_modules(). and/or are boolean
expressions, not operator modules. filter.ex:135-142 registers the aliases equals, not_equals,
gt, lt, gte, lte. Treat the guide’s list as a readable rendering of the registered list.

5.4 Expression functions

lib/ash/filter/filter.ex:76-116 registers 39 functions:
Ago, At, CompositeType, Contains, CountNils, DateAdd, DateTimeAdd, Fragment,
FromNow, GetPath, Has, IsDistinctFrom, IsNil, IsNotDistinctFrom, If, Intersects,
Lazy, Length, Minus, Now, RangeAdjacent, RangeContains, RangeLower, RangeOverlaps,
RangeUpper, Error, Rem, Round, Today, Type, StartOfDay, StringDowncase,
StringEndsWith, StringJoin, StringLength, StringPosition, StringSplit,
StringStartsWith, StringTrim.

The guide documents a readable subset of these plus the special forms exists/2, path.exists/2
and parent/1 (documentation/topics/reference/expressions.md:69-91, :106-130, :135-139),
inline aggregates (:141-184), error expressions (:414-482) and lazy/1 (:137).

5.5 Expression templates — 5, not 6

The guide documents 4 (:190-197); the source has a 5th, ^tenant() (lib/ash/expr/expr.ex:106,
expanded at :277). parent/1 and path.exists/2 are sub-expressions, not templates
(expressions.md:117, :118).

^actor(:key) # equivalent to `get_in(actor || %{}, [:key])`
^actor([:key1, :key2]) # equivalent to `get_in(actor || %{}, [:key, :key2])`
^arg(:arg_name) # equivalent to `Map.get(arguments, :arg_name)`
^context(:key) # equivalent to `get_in(context, :key)`
^context([:key1, :key2]) # equivalent to `get_in(context, [:key1, :key2])`
^ref(:key) # equivalent to referring to `key`. Allows for dynamic references
^ref([:path], :key) # equivalent to referring to `path.key`. Allows for dynamic references with dynamic (or static) paths.

(verbatim, documentation/topics/reference/expressions.md:190-197; ^tenant() is at
lib/ash/expr/expr.ex:106)

---

6. Policies

Guide: documentation/topics/security/policies.md. DSL: documentation/dsls/DSL-Ash.Policy.Authorizer.md.

6.1 Structure and options

• policy — options are exactly four (lib/ash/policy/authorizer/authorizer.ex:166-202):
  description, access_type (:strict | :filter | :runtime, :170-175), condition (:176-181,
  “A check or list of checks that must be true in order for this policy to apply”) and
  error_message (:182-201, a string or a 2-arity (subject, context) function). Its
  condition is an ordinary check such as action_type(:read). Its entities are the four check
  forms authorize_if, forbid_if, authorize_unless, forbid_unless.
• bypass — same four check entities; if a bypass passes, later policies need not
  (documentation/topics/security/policies.md:151-154).
• policy_group — “groups a set of policies together by some condition. If the condition on the
  policy group does not apply, then none of the policies within it apply”
  (lib/ash/policy/authorizer/authorizer.ex:222-224). Groups nest.
• field policies — field_policy takes fields (positional, :wrap_list), description and
  an optional condition, plus the four check entities (:335-367); field_policy_bypass is the
  same with bypass?: true (:370-376). “If any field policies exist then all fields must be
  authorized by a field policy” (:387), except primary keys (:392); the deny-list style uses
  the special field name :* (:389). Forbidden fields become %Ash.ForbiddenField{}.

Decision rule: checks run top to bottom; the first to return :authorized/:forbidden decides the
policy; :unknown falls through. If all are :unknown, the policy is treated as forbidden
(documentation/topics/security/policies.md:78-115, :609-620).

Realistic example (verbatim, documentation/topics/security/policies.md:159-178):

policies do
  # Anything you can use in a condition, you can use in a check, and vice-versa
  # This policy applies if the actor is a super_user
  # Additionally, this policy is declared as a `bypass`. That means that this check is allowed to fail without
  # failing the whole request, and that if this check *passes*, the entire request passes.
  bypass actor_attribute_equals(:super_user, true) do
    authorize_if always()
  end

  # This will likely be a common occurrence. Specifically, policies that apply to all read actions
  policy action_type(:read) do
    # unless the actor is an active user, forbid
    forbid_unless actor_attribute_equals(:active, true)
    # if the record is marked as public, authorize
    authorize_if expr(public == true)
    # if the actor is related to the data via that data's `owner` relationship, authorize
    authorize_if relates_to_actor_via(:owner)
  end
end

6.2 Access types

access_type decides the latest point at which a check may be applied
(documentation/topics/security/policies.md:227-244). Default :filter; the resource-level
section option is default_access_type (lib/ash/policy/authorizer/authorizer.ex:325-331).

6.3 Built-in checks (complete, 22)

lib/ash/policy/check/built_in_checks.ex: always (24), never (35), action_type (62),
just_created_with_action (73), action (83), resource (91), private_action? (108),
actor_present (116), actor_absent (124), filtering_on (165), selecting (194), loading (204),
accessing_from (229), relates_to_actor_via (256), can_read (328), actor_attribute_equals
(340), context_equals (361), changing_attributes (386), relating_to_actor (407),
changing_relationship (412), changing_relationships (417), matches macro (422).

6.4 Check kinds

• Simple check (documentation/topics/security/policies.md:617) — use Ash.Policy.SimpleCheck
  (:625), implement describe/1 and match?/3; returns true/false.
• Filter check (:662) — use Ash.Policy.FilterCheck (:677), implement filter/3.
• Inline checks (:704) — filter checks written directly in the policy (:711).
• Manual check — the supertype both of the above fall under (:609).

6.5 Reads vs writes

“Read actions are, by default, filtered by policies rather than returning authorization errors”
(:126). Forbidden records do not appear; a single-record read then yields NotFound. Opt out
with authorize_with: :error (:136-149). Filter checks on update/destroy apply before the action
runs; on create they run against the inserted row inside the transaction (:122, :229-233).
Cross-resource composition uses can_read and accessing_from (:516-579); relationships carry
authorize_read_with and allow_forbidden_field? (:467-515).

6.6 error_message and debugging

A policy’s error_message is a string or a (subject, context) function; the function may return
an Exception.t() that “replaces the default Ash.Error.Forbidden.Policy entirely” and
otherwise sets the message (lib/ash/policy/authorizer/authorizer.ex:186-200; guide :370-447).
Policy breakdowns and logging: :967-1047.

6.7 Ash.can? and friends

lib/ash.ex:1840 can?/3 (spec: “Ash.Can.subject(), actor() | Ash.Scope.t(), Keyword.t()”),
:1963 can/3, :2063 can_see_fields?/4, :2101 can_see_fields/4, :2164
can_do_all?/2, :2207 can_do_all/2.

6.8 Default when no policy applies

Settled from source. raw_expression/1 folds the applicable policies from {false, true}
(lib/ash/policy/policy.ex:81) and returns one_condition_matches and all_policies_match (:97).
With zero applicable policies that is false, so a request no policy applies to is
forbidden. A bypass counts toward “at least one applies” only if it authorizes (:85-86).
Separately the authorizer is opt-in: a resource has policy authorization only if it declares
authorizers: [Ash.Policy.Authorizer] (policies.md:20).

6.9 Actors and Ash.Scope

Actor/tenant/authorize are passed per call as actor:, tenant:, authorize?:, and scope:
options (documentation/topics/security/actors-and-authorization.md). Ash.Scope
(lib/ash/scope.ex) determines how actor, tenant and context are extracted from a data
structure: the user implements the Ash.Scope.ToOpts protocol for their own struct so the actor,
tenant, context, authorize? and tracer can be pulled out of it (lib/ash/scope.ex:5-12,
:55-61). Sensitive data:
documentation/topics/security/sensitive-data.md.

---

7. Multitenancy

documentation/dsls/DSL-Ash.Resource.md:4310-4348, guide
documentation/topics/advanced/multitenancy.md.

multitenancy do
  strategy :attribute
  attribute :organization_id
  global? true
end

(verbatim, documentation/dsls/DSL-Ash.Resource.md:4323-4327)

Tenant is set with Ash.Query.set_tenant/2 or Ash.Changeset.set_tenant/2 (:4315) or
Ash.PlugHelpers.set_tenant / Ash.Scope (documentation/topics/advanced/multitenancy.md:31-64).

The per-action/calculation multitenancy override is :enforce | :allow_global | :bypass | :bypass_all, default :enforce (e.g. :1220). It exists on create, read, update, destroy
(:1220, :1514, :1857, :2147) and on calculations (:4244) — not on generic action
(:985-994). Identities have all_tenants? (:2828). Guide sections: “Setting Tenant” (:31),
“Attribute Multitenancy” (:66), “Transforming Tenant Values” (:140), “Tenant-Aware Identities”
(:189), “Context Multitenancy” (:245), “Possible Values for tenant” (:256).

---

8. Code interfaces, Ash.Changeset, Ash.Query, Ash.ActionInput, Ash.*

8.1 code_interface

Section options (:2428-2436): domain, define?, namespace.

code_interface do
  define :create_user, action: :create
  define :get_user_by_id, action: :get_by_id, args: [:id], get?: true
end

(verbatim, documentation/dsls/DSL-Ash.Resource.md:2418-2421)

define options (:2466-2480): action, args, not_found_error? (default true),
require_reference?, exclude_inputs, get?, get_by, get_by_identity, default_options,
namespace, and functions — which by default generates all five of
:subject, :can, :can?, :action, :action! (:2478).

define_calculation options (:2614-2620): calculation, exclude_inputs, args
(:name, {:arg, :name}, {:ref, :name}), namespace. Use :_record to take a record instance.

Both can be declared on the resource or on the domain’s resources.resource
(documentation/dsls/DSL-Ash.Domain.md:107-291). Guide:
documentation/topics/resources/code-interfaces.md.

8.2 Ash.Changeset public API

Public functions in lib/ash/changeset/changeset.ex (@doc false internals excluded):
new (508), select (592), load (688), ensure_selected (723), deselect (739),
selecting? (753), loading? (783), accessing (795), fully_atomic_changeset (813),
atomic_defaults (895), atomic_ref (1703), for_action (1934),
for_create (2100), for_update (2210), for_destroy (2293), atomic_update (2417, 2498),
atomic_set (2607, 2614), set_result (2900), expand_upsert_fields (2908-2925),
present? (3140), attribute_present? (3176), prepare_changeset_for_action (3196), with_hooks (4743), run_before_transaction_hooks (5066),
get_argument (5438, 5446), fetch_argument (5462, 5475), get_attribute (5491),
fetch_attribute (5513), get_argument_or_attribute (5525),
fetch_argument_or_attribute (5544), fetch_argument_or_change (5559),
fetch_change (5553), get_data (5568), fetch_data (5596), put_context (5606),
set_tenant (5611), as_of (5628, 5630), timeout (5642), set_context (5652, 5654),
manage_relationship (6136), changing_attributes? (6564), changing_attribute? (6605),
changing_relationship? (6613), change_new_attribute (6619), change_new_attribute_lazy (6636),
force_change_new_attribute (6896), force_change_new_attribute_lazy (6910),
update_change (6671), set_argument (6720), set_private_argument (6729),
force_set_argument (6784), delete_argument (6849), force_delete_argument (6862),
set_arguments (6873), force_set_arguments (6884), change_attributes (6948), change_attribute (6989),
change_default_attribute (7114), force_change_attributes (7138), force_change_attribute (7146),
before_action (7326), before_transaction (7389), after_action (7471),
after_transaction (7607), around_action (7677), around_transaction (7731),
clear_change (7782), handle_errors (7818), filter (7832), add_error (7901),
apply_attributes (7758).

get_result and run_atomic_conditions do not exist. handle_allow_nil_atomics (2817),
hydrate_atomic_refs (3825), validate_multitenancy (3495) — and the runners
run_before_actions (5115), run_after_transactions (5205), run_after_actions (5308),
split_atomic_conditions (1169), run_atomic_validation (1217), run_atomic_change (1300),
set_on_upsert (2930), handle_params (3222), require_values (4517), manage_relationship_opts
(5697), manage_relationship_schema (6010), set_action_select (613), atomic_condition (1743),
temporal_recorded_at (4307) and set_private_arguments_for_action (6739) — are @doc false
internals.

8.3 Ash.* top-level functions

lib/ash.ex: create/2, update/3, destroy/2, get/3, get!, read/2, read!, read_one/2,
read_one!, read_first/2, read_first!, load/3, load!, update_many/3, update_many!,
first/2, list/2, page/2, page!, reload/2, stream!/2, count/2, exists/2, exists?/2,
sum/3, max/3, min/3, avg/3, aggregate/3, calculate/3, bulk_create/3, bulk_update/4,
bulk_destroy/4 and the bang variants, run_action/2, transact/3, transaction/3,
data_layer_query/2, pkey_filter/2, plus can?, can, can_see_fields?, can_see_fields,
can_do_all?, can_do_all (:1840-2207) and the *_opts helpers (:1061, :1066, :1103).
Arities are the maximum ones: exists/2, exists?/2, aggregate/3, run_action/2 and
data_layer_query/2 each take an optional opts keyword list as their last argument
(lib/ash.ex:1193, :1299, :1329, :2299, :3086); pkey_filter/2 takes (records, pkey)
(:4642).

8.4 Ash.ActionInput

The generic-action counterpart of Changeset/Query (lib/ash/action_input.ex), built by
Ash.ActionInput.for_action/4 (lib/ash/action_input.ex:253) and carrying error_handler
(documentation/dsls/DSL-Ash.Resource.md:988).

---

9. Identities, resource-level validations, notifiers, pub_sub

Identities (:2785-2833). identity name, keys; 10 options: where, nils_distinct?
(default true), eager_check?, eager_check_with, pre_check?, pre_check_with, description,
field_names, message, all_tenants? (:2828).

identities do
  identity :full_name, [:first_name, :last_name]
  identity :email, [:email]
end

(verbatim, documentation/dsls/DSL-Ash.Resource.md:2775-2778)

Resource-level validations (:2976-3041). validate validation applies to creates and updates
by default (on:, default [:create, :update], :3030); options where, on, only_when_valid?,
message, description, before_action?, always_atomic?. The same mechanism backs the
preparations (:2913) and changes (:2841) sections; pipelines (:3048) names a reusable
bundle attached with pipe_through (:1127-1160).

Notifiers. Attached to the resource — use Ash.Resource, notifiers: [ExampleNotifier], or
simple_notifiers: to avoid a compile-time dependency — or to a single action —
create :create do notifiers [ExampleNotifier] end (documentation/topics/resources/notifiers.md:33-56).
A notifier implements one callback, notify/1; it “does not have to implement an Ash DSL extension,
but they may” (:65-70). Notifiers run after commit (:113).

PubSub. The builtin is Ash.Notifier.PubSub, configured through a pub_sub section
(documentation/dsls/DSL-Ash.Notifier.PubSub.md:147) with entities publish and publish_all.
Topic templates are a list whose atoms are replaced by record values and joined with :
(:43-56):

pub_sub do
  module MyAppWeb.Endpoint
  prefix "post"

  publish :create, "created", load: [:comment, author: [:full_name]]
  publish :update, ["updated", :id], load: [:comment, author: [:full_name]]
end

(verbatim, documentation/dsls/DSL-Ash.Notifier.PubSub.md:135-141)

broadcast_type selects :notification, :phoenix_broadcast or :broadcast (:116-125).
load: on a publication preloads fields before broadcasting, deduplicated across publications
(:127-146).

---

10. Errors

10.1 Basis: Splode

Ash errors are not hand-rolled. Ash.Error does
use Splode, error_classes: [forbidden: Ash.Error.Forbidden, invalid: Ash.Error.Invalid, framework: Ash.Error.Framework, unknown: Ash.Error.Unknown], merge_with: [Reactor.Error], filter_stacktraces: ["Ash.", "Splode."], unknown_error: Ash.Error.Unknown.UnknownError
(lib/ash/error/error.ex:9-18). The Splode library defines the shared struct: 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), and error classes also add errors: []
(scratch/ash-src/splode/lib/splode/error_class.ex:11). Ash re-exports it; the definitions at
lib/ash/error/error.ex:20-37 are only @types. Splode version examined: 0.3.2
(scratch/ash-src/splode/mix.exs:8), the version pinned by ash’s mix.lock:53.

Ash.Error.to_error_class/2 (:78-96) reduces a changeset/query/action-input to one of the four
classes; to_ash_error/3 (:53) converts any exception into an Ash error.

10.2 Classes

10.3 Leaves — 91 modules

lib/ash/error/ holds 99 .ex files; 8 are top-level (error.ex, error_kind.ex, exception.ex,
stacktrace.ex, invalid.ex, forbidden.ex, framework.ex, unknown.ex), leaving 91 leaf
modules. Representative list:

• changes/: required, invalid_attribute, no_such_attribute, invalid_relationship,
  no_such_relationship, invalid_argument, action_requires_actor, stale_record,
  period_out_of_bounds
• query/: not_found, no_read_action, read_action_required, invalid_filter_reference,
  invalid_sort, invalid_limit, invalid_offset, no_such_operator, no_such_function,
  calculation_requires_primary_key, unsupported_predicate, as_of_not_an_instant
• invalid/: no_primary_action, no_such_action, invalid_primary_key, tenant_required,
  pagination_required, action_requires_pagination, multiple_results
• forbidden/: policy, domain_requires_actor, domain_requires_authorization,
  forbidden_field, must_pass_strict_check, cannot_filter_creates
• framework/: must_be_atomic, can_not_be_atomic, pending_codegen, load_over_range
• unknown/: invalid_casted_value, invalid_stored_value

10.4 Shape and catching

Errors are returned as {:error, %Ash.Error.X{}}; bang variants raise. Tutorial output
(verbatim, documentation/tutorials/get-started.md:305-307):

** (Ash.Error.Invalid) Invalid Error

* attribute subject is required

The non-bang form returns the struct (documentation/tutorials/get-started.md:398-403):

{:error,
 %Ash.Error.Invalid{
...
       message: "Ticket is already closed",
...

error_handler on the action sets the handler on the changeset or action input
(:1234, :988); Ash.Changeset.handle_errors/2 and Ash.ActionInput.handle_errors/2 are the
APIs. Guide: documentation/topics/development/error-handling.md.

---

11. Tooling shipped with core

11.1 Mix tasks — 25

14 top-level (lib/mix/tasks/*.ex): ash.codegen, ash.ex, ash.extend,
ash.generate_livebook, ash.generate_policy_charts (module Mix.Tasks.Ash.GeneratePolicyCharts,
lib/mix/tasks/ash.generate_policy_chart.ex:5), ash.generate_resource_diagrams,
ash.gettext.extract, ash.manifest.dump, ash.migrate, ash.reset, ash.rollback,
ash.set.domains, ash.setup, ash.tear_down.

9 generators (lib/mix/tasks/gen/*.ex): ash.gen.base_resource, ash.gen.change,
ash.gen.custom_expression, ash.gen.domain, ash.gen.enum, ash.gen.gettext,
ash.gen.preparation, ash.gen.resource, ash.gen.validation.

2 more: lib/mix/tasks/install/ash.install.ex (installer),
lib/mix/tasks/patch/ash.patch.extend.ex (patcher).

lib/mix/tasks/helpers.ex is a helper module, not a task. The generators guide has sections
## Installer (documentation/topics/development/generators.md:13), ## Generators (:45) and
## Patchers (:56). lib/mix/mermaid.ex is a rendering helper.

11.2 Formatter

.formatter.exs exports spark_locals_without_parens (:5), a long list of DSL keyword names the
Elixir formatter must not put parentheses around (e.g. accept: 1, action_select: 1,
allow_nil?: 1). This is how the paren-free DSL stays readable.

11.3 Cheat sheets and LLM docs

• The documentation/dsls/DSL-*.md files are Spark-generated cheat sheets for every DSL
  (the header of documentation/dsls/DSL-Ash.Resource.md:2 reads “This file was generated by
  Spark. Do not edit it by hand.”).
• documentation/topics/reference/glossary.md — the Elixir-for-Ash vocabulary.
• documentation/2.0-CHANGELOG.md — migration notes, not a cheat sheet.
• usage-rules.md plus usage-rules/ (14 files: actions.md, aggregates.md,
  authorization.md, calculations.md, code_interfaces.md, code_structure.md,
  data_layers.md, exist_expressions.md, generating_code.md, migrations.md,
  query_filter.md, querying_data.md, relationships.md, testing.md) — rules written for AI
  agents coding against Ash.
• documentation/topics/development/working-with-llms.md — how to use Ash with LLMs.
• documentation/how-to/*.livemd — 7 executable how-to guides: test-resources,
  authorize-access-to-resources, write-queries, polymorphic-relationships,
  encrypt-attributes, prevent-concurrent-writes (optimistic_lock), wrap-external-apis.

11.4 Tracing / telemetry

documentation/topics/advanced/monitoring.md — 18 telemetry events, each emitted twice with
:start and :stop suffixes (:17-44):

• [:ash, domain_short_name, :create | :update | :read | :destroy | :action | :bulk_create | :bulk_update | :bulk_destroy]
• [:ash, :changeset], [:ash, :query], [:ash, :validation], [:ash, :change],
  [:ash, :calculation], [:ash, :before_action], [:ash, :after_action],
  [:ash, :preparation], [:ash, :notifier], [:ash, :request_step]

Start events carry system_time; stop events carry system_time and duration (:17). There are
also 18 trace types (:75-92). Both resources and domains accept trace_name
(documentation/dsls/DSL-Ash.Resource.md:2751, documentation/dsls/DSL-Ash.Domain.md:423).
Timeouts: execution timeout on the domain (documentation/dsls/DSL-Ash.Domain.md:422) and
timeout on read actions (documentation/dsls/DSL-Ash.Resource.md:1513). Guides:
documentation/topics/advanced/timeouts.md and, for the temporal DSL section,
documentation/topics/advanced/temporal-resources.md.

11.5 Built-in data layers

Ash.DataLayer.Simple (the default, lib/ash/resource.ex:25), Ash.DataLayer.Ets and
Ash.DataLayer.Mnesia (lib/ash/data_layer/{ets,mnesia,simple}), with DSL references
documentation/dsls/DSL-Ash.DataLayer.Ets.md and DSL-Ash.DataLayer.Mnesia.md. SQL data layers
live in ash_sql/ash_postgres — owned by ash-ecosystem.

11.6 Testing support

Ash.Generator (lib/ash/generator/generator.ex), Ash.Seed (lib/ash/seed.ex), Ash.Test
(lib/ash/test.ex); guide documentation/topics/development/testing.md.

11.7 Ash.Reactor in core

Core ships an Ash.Reactor DSL (documentation/dsls/DSL-Ash.Reactor.md) for composing multi-step
work across actions; guides documentation/topics/advanced/reactor.md and
documentation/topics/advanced/multi-step-actions.md. A generic action’s run accepts a Reactor
module directly (§4.1). The standalone Reactor library and its ecosystem integrations are owned by
ash-ecosystem.

---

12. Density example

The official getting-started tutorial’s Helpdesk.Support.Ticket, assembled from its 7 verbatim
fragments. Each block is quoted in full including its comment lines. The tutorial is incremental,
so this is a concatenation, not one contiguous listing.

This resource uses 3 of the 14 Ash.Resource sections — attributes (:47), actions (:12),
relationships (:33). It has no policies, identities, aggregates, calculations,
code_interface, multitenancy, changes, preparations, validations or pipelines. In the
ash clone itself there is no documented example resource that uses most sections — the richest
complete resources are assembled across the guide snippets cited in §2–§10. A denser real
resource does exist outside the clone, in the Ash book’s sample app; it is quoted in §12.1 below.

# documentation/tutorials/get-started.md:159-178
defmodule Helpdesk.Support.Ticket do
  # This turns this module into a resource
  use Ash.Resource, domain: Helpdesk.Support

  actions do
    # Use the default implementation of the :read action
    defaults [:read]

    # and a create action, which we'll customize later
    create :create
  end

  # Attributes are the simple pieces of data that exist on your resource
  attributes do
    # Add an autogenerated UUID primary key called `:id`.
    uuid_primary_key :id

    # Add a string type attribute called `:subject`
    attribute :subject, :string
  end
end

# documentation/tutorials/get-started.md:236-261
attributes do
  ...
  attribute :subject, :string do
    # Don't allow `nil` values
    allow_nil? false

    # Allow this attribute to be public. By default, all attributes are private.
    public? true
  end

  # status is either `open` or `closed`. We can add more statuses later
  attribute :status, :atom do
    # Constraints allow you to provide extra rules for the value.
    # The available constraints depend on the type
    # See the documentation for each type to know what constraints are available
    # Since atoms are generally only used when we know all of the values
    # it provides a `one_of` constraint, that only allows those values
    constraints [one_of: [:open, :closed]]

    # The status defaulting to open makes sense
    default :open

    # We also don't want status to ever be `nil`
    allow_nil? false
  end
end

(leading ... marks lines elided from the tutorial itself, which uses them as placeholders)

# documentation/tutorials/get-started.md:267-274
# lib/helpdesk/support/ticket.ex

actions do
  ...
  create :open do
    accept [:subject]
  end
end

# documentation/tutorials/get-started.md:317-335
# lib/helpdesk/support/ticket.ex

actions do
  ...
  update :close do
    # We don't want to accept any input here
    accept []

    validate attribute_does_not_equal(:status, :closed) do
      message "Ticket is already closed"
    end

    change set_attribute(:status, :closed)
    # A custom change could be added like so:
    #
    # change MyCustomChange
    # change {MyCustomChange, opt: :val}
  end
end

# documentation/tutorials/get-started.md:476-478
use Ash.Resource,
  domain: Helpdesk.Support,
  data_layer: Ash.DataLayer.Ets

# documentation/tutorials/get-started.md:561-567
relationships do
  # belongs_to means that the destination attribute is unique, meaning only one related record could exist.
  # We assume that the destination attribute is `representative_id` based
  # on the name of this relationship and that the source attribute is `representative_id`.
  # We create `representative_id` automatically.
  belongs_to :representative, Helpdesk.Support.Representative
end

# documentation/tutorials/get-started.md:595-598
update :assign do
  accept [:representative_id]
end

What Ash derives from that one file

Every row below is a derivation the source states explicitly. The inverse has_many :tickets on
Representative is not derived — the tutorial has the user declare it by hand (:547-551).

12.1 A dense real resource: Tunez.Music.Album

From the Ash book’s sample app Tunez (Rebecca Le, sevenseacat/tunez), file
lib/tunez/music/album.ex on branch end-of-chapter-10, commit
5ea6daeac0d8634bca22cddd3fc7331f6391f3c3:
https://github.com/sevenseacat/tunez/blob/end-of-chapter-10/lib/tunez/music/album.ex.
The file is 146 lines. The branch’s mix.lock pins ash 3.12.0 — older than the 3.33.11 clone
the rest of this document cites (fetched 2026-10-01; the main branch is the starter app and has
no album.ex, hence the branch pin). Quoted verbatim, abridged — each omission is named inline:
the json_api and postgres extension sections, two attribute blocks, the validations
section, and the def next_year helper at album.ex:88 that its numericality validation calls.
Nothing else is removed.

defmodule Tunez.Music.Album do
  use Ash.Resource,
    otp_app: :tunez,
    domain: Tunez.Music,
    data_layer: AshPostgres.DataLayer,
    extensions: [AshGraphql.Resource, AshJsonApi.Resource],
    authorizers: [Ash.Policy.Authorizer]

  graphql do
    type :album
  end

  # (abridged: the `json_api` and `postgres` extension sections are omitted)

  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

  changes do
    change Tunez.Accounts.Changes.SendNewAlbumNotifications, on: [:create]

    change relate_actor(:created_by, allow_nil?: true), on: [:create]
    change relate_actor(:updated_by, allow_nil?: true)
  end

  # (abridged: `validations` — `numericality(:year_released, ...)` and
  # `match(:cover_image_url, ...)`, both with `where:` and `message:` — omitted)

  # (abridged: `def next_year, do: Date.utc_today().year + 1` (album.ex:88) is omitted)

  attributes do
    uuid_primary_key :id

    attribute :name, :string do
      allow_nil? false
      public? true
    end

    # (abridged: the `:year_released` and `:cover_image_url` attribute blocks are omitted)

    create_timestamp :inserted_at
    update_timestamp :updated_at
  end

  relationships do
    belongs_to :artist, Tunez.Music.Artist do
      allow_nil? false
    end

    has_many :tracks, Tunez.Music.Track do
      sort order: :asc
      public? true
    end

    has_many :notifications, Tunez.Accounts.Notification

    belongs_to :created_by, Tunez.Accounts.User
    belongs_to :updated_by, Tunez.Accounts.User
  end

  calculations do
    calculate :duration, :string, Tunez.Music.Calculations.SecondsToMinutes

    calculate :can_manage_album?,
              :boolean,
              expr(
                ^actor(:role) == :admin or
                  (^actor(:role) == :editor and created_by_id == ^actor(:id))
              )
  end

  aggregates do
    sum :duration_seconds, :tracks, :duration_seconds
  end

  identities do
    identity :unique_album_names_per_artist, [:name, :artist_id],
      message: "already exists for this artist"
  end
end

Sections used: 8 of the 14 Ash.Resource sections — actions, changes, validations,
attributes, relationships, calculations, aggregates, identities — plus policies (from
the Ash.Policy.Authorizer extension) and 3 extension sections (graphql, json_api, postgres).

The code interface is declared on the domain, not the resource. Same branch,
lib/tunez/music.ex:68-73 (verbatim):

    resource Tunez.Music.Album do
      define :create_album, action: :create
      define :get_album_by_id, action: :read, get_by: :id
      define :update_album, action: :update
      define :destroy_album, action: :destroy
    end

What Ash derives from it:

The runner-up inside the ash clone is test/support/policy_complex/resources/post.ex (120
lines), but it is test scaffolding, not a documented example.

---

13. Coverage against the Mesh plan

Plan: notes/Ash-style Resource Framework on MX + TypeScript Implementation Plan.md (204 lines).
Factual mapping only.

---

Open questions

1. managing-relationship guide depth. The type: values are read from
   lib/ash/changeset/changeset.ex:5697-5743; the full option list per type lives in
   documentation/topics/resources/relationships.md, which I did not read.
2. custom_expression generator and Ash.CustomExpression are named but their callback set is
   only summarised (documentation/topics/reference/expressions.md:200-215).
3. Combination queries. Named from lib/ash/query/query.ex function names plus the guide’s
   existence; I did not read the guide.
4. Web sources. Only one was needed: the Tunez sample app for §12.1. Everything else is a local
   path:line from ash 3.33.11 (and splode 0.3.2 for §10.1).

---

Implications for Mesh (researcher’s analysis)

1. The closed vocabulary is the asset, and this review proved it. The lists failed in three
   different ways, and the failure mode mattered: the types list came from a file listing
   instead of the registered set; the changes, preparations and checks lists came from
   grep ' def ', which silently misses defmacro; the expression-function list came from the
   guide instead of filter.ex:76-116. In every case Ash keeps the authoritative list in one
   place — @builtin_short_names in registry.ex:8-40, the add_expression_function/3 calls in
   filter.ex — and docs, generators and errors all derive from it. Mesh should do the same: one
   registry per vocabulary, read by the compiler, the docs generator and the error messages. A
   list in prose is a liability; a list in a data file is an asset. The tooling lesson generalises:
   a generator that reads the registry, not a human reading a directory.
2. Registered vs documented is where DX is lost. 39 registered expression functions vs ~30
   documented; 22 policy checks vs 21 obvious ones. The plan already has the slot: the
   machine-readable IR plus <cli> inspect. A <cli> list-checks printing exactly what the
   compiler accepts, with no prose drift, is the cheap fix.
3. Ash.Scope is a small idea with large leverage. Bundling {actor, authorize?, tenant, context} into one value gives those four a single place to live, and makes “how was this call
   authorized?” answerable in one place. Note what it is not: the options are not removed — “the
   actor, tenant and context options will always remain available”
   (lib/ash/scope.ex:7-9), and explicit options override values taken from the scope. It is an
   alternative way to pass the same values, not a replacement. The plan has no equivalent; generated
   handlers would otherwise thread actor/tenant by hand.
4. Access types (:strict/:filter/:runtime) are the most transferable idea here. They
   separate “must be checked before the DB call” from “may be a SQL filter” — the same split the
   plan already has as “translatable” vs “opaque” expressions. Wiring access_type into that split
   is nearly free and prevents the silent in-memory fallback the plan forbids (plan:89).
5. Error classes map 1:1 onto HTTP status codes. Naming the four up front means the OpenAPI
   generator and api-http need no per-error special-casing.
6. Everything opt-in is load-bearing. The authorizer is opt-in via authorizers:; the data
   layer defaults to Ash.DataLayer.Simple; simple_notifiers exists to avoid compile-time
   dependencies. A resource that declares nothing still works. Mesh’s tag set should behave the
   same: an empty resource compiles and runs.
7. Density, measured honestly. The clone’s tutorial uses 3 of 14 sections; the book’s sample
   app reaches 8 (§12.1); the plan’s own uses 5. “Full Ash parity in v1” (plan:26) is consistent
   with that — but so is naming those 5 as the explicit v1 target instead of leaving it to the
   mapping table.
8. usage-rules/ is the cheapest lesson in agent legibility. 14 files of prose rules shipped
   in the framework, written for exactly the plan’s audience. It costs almost nothing and matches
   the plan’s existing “Skill file ships with the framework” principle (plan:172).

Revision log (round 2)

Round 3

Round 4

Sources

Web:

• Tunez.Music.Album, sevenseacat/tunez, branch end-of-chapter-10, commit
  5ea6daeac0d8634bca22cddd3fc7331f6391f3c3 (pins ash 3.12.0), fetched 2026-10-01:
  https://github.com/sevenseacat/tunez/blob/end-of-chapter-10/lib/tunez/music/album.ex and
  lib/tunez/music.ex:68-73 on the same branch. Used only in §12.1.

Local (all under scratch/ash-src/):

• ash/ (3.33.11): documentation/dsls/DSL-Ash.Resource.md, DSL-Ash.Domain.md,
  DSL-Ash.Policy.Authorizer.md, DSL-Ash.Notifier.PubSub.md, DSL-Ash.TypedStruct.md,
  DSL-Ash.Reactor.md; documentation/tutorials/get-started.md;
  documentation/topics/ (security/policies.md, security/actors-and-authorization.md,
  security/sensitive-data.md, advanced/multitenancy.md, advanced/monitoring.md,
  advanced/combination-queries.md, advanced/timeouts.md, advanced/temporal-resources.md,
  advanced/reactor.md, reference/expressions.md, resources/*.md,
  development/generators.md, development/testing.md); documentation/how-to/ (7 files);
  usage-rules.md, usage-rules/ (14 files);
  lib/ash.ex, lib/ash/resource.ex, lib/ash/scope.ex, lib/ash/action_input.ex,
  lib/ash/changeset/changeset.ex, lib/ash/query/query.ex,
  lib/ash/resource/{change,preparation,validation}/builtins.ex,
  lib/ash/resource/{change/change.ex,preparation/preparation.ex,validation.ex},
  lib/ash/resource/calculation/calculation.ex,
  lib/ash/resource/manual_relationship/manual_relationship.ex,
  lib/ash/policy/{authorizer/authorizer.ex,policy.ex,check/built_in_checks.ex},
  lib/ash/filter/filter.ex, lib/ash/query/operator/basic.ex, lib/ash/expr/expr.ex,
  lib/ash/type/registry.ex, lib/ash/type/{new_type.ex,enum.ex}, lib/ash/typed_struct.ex,
  lib/ash/error/ (99 files), lib/ash/data_layer/{ets,mnesia,simple},
  lib/ash/type_resolver.ex, lib/ash/actions/read/async_limiter.ex,
  lib/mix/tasks/ (25 tasks), .formatter.exs, mix.exs, mix.lock.
• splode/ (0.3.2): lib/splode/error.ex, lib/splode/error_class.ex, mix.exs.
• notes/Ash-style Resource Framework on MX + TypeScript Implementation Plan.md (the Mesh plan, §13).