ServiceRadar Elixir Rules

Database migration command

• Bringing a database up to date: mix serviceradar.db.migrate, NOT mix ecto.migrate. An empty database is built from the committed baseline and only newer migrations run; mix ecto.migrate replays every migration in the tree instead, which is slow and has failed outright against a remote instance. Pass --no-baseline only when you deliberately want the full replay. The baseline does not work on a database that already carries TimescaleDB hypertables or AGE graphs, which is every real one — the schema does not round-trip, so the fixture lifecycle replays on an empty database instead. Do not reintroduce baselining there; why it cannot work is in docs/agent-runbooks.md.

Quality commands

• Elixir workspace quality contract: ./scripts/elixir_quality.sh --project elixir/<project> and add --phoenix for Phoenix apps such as elixir/web-ng. PRs gate --lint-only (format + Credo); the rest of the Mix contract runs daily from //buildbuddy.yaml.
• Same format/Credo check, hermetic on RBE and needing no local Hex deps/: bazel test --config=remote //build/elixir_quality:quality_check; auto-fix with bazel run --config=remote //build/elixir_quality:format. See build/elixir_quality.bzl for how Mix inputs are supplied.
• Elixir / Dialyzer: prefer idiomatic Elixir (MapSet.new/1, direct GRPC.Stub.connect/2, normal Ash reads). Treat Dialyzer as advisory for false positives (opaque types, incomplete PLT success typing). See Hard Rules — never degrade APIs to silence the type checker. Use mix dialyzer --format dialyzer when Dialyxir short format crashes on unknown warning kinds.

Dialyzer

• Never degrade production code to silence Dialyzer (or similar type checkers). Idiomatic, readable APIs beat warning-count optimization. Do not introduce runtime shape hacks, opacity barriers, or non-idiomatic call patterns whose only purpose is to make Dialyzer happy. Forbidden patterns include (non-exhaustive):

  • :erlang.apply(MapSet, :new, …) / apply(Mod, :fun, …) / variable-module apply solely to hide success typing
  • “opaque_call” / 0-arity fun wrappers / :erlang.binary_to_term(term_to_binary(…)) barriers around otherwise normal calls
  • Rewriting clear MapSet / URI / gRPC / Ash call sites into obscure forms to dodge opaque-type or error-only success typing noise
  • Broad “fix everything Dialyzer mentions” sweeps that churn APIs without a product or correctness win

  Allowed approaches, in order:

  1. Fix a real bug or wrong typespec with a clean, idiomatic change (and tests when behavior changes).
  2. Leave a false positive alone, or add a narrow, documented entry in the project’s .dialyzer_ignore.exs (file + warning kind or short description — never directory-wide suppressions).
  3. If Dialyxir cannot render a warning kind (e.g. :opaque_compare), report or work around the formatter, do not reshape application code for it.

  Historical note: PR #4677 chased Dialyzer counts with apply/opaque barriers and MapSet churn; it was fully reverted in #4679. Do not reintroduce that style.

External downloads and dependencies

• Use ServiceRadar.HTTP.EgressClient for external artifact downloads. Its module documentation owns the streaming contract and CONNECT-proxy compatibility rationale. The regression coverage is in elixir/serviceradar_core/test/serviceradar/http/egress_client_test.exs.
• Check the workspace Hex closure when Mix and release dependencies differ. The Hex build definition owns the cross-project resolution policy; third_party/hex/hex_packages.bzl records the generated versions shipped by Bazel.

Iron Laws

• LiveView: no database queries in disconnected mount. Use streams for lists larger than 100 items. Check connected?/1 before PubSub subscribe.
• Ecto: never use :float for money. Always pin values with ^ in queries. Use separate queries for has_many, JOIN for belongs_to.
• Oban: jobs must be idempotent. Args use string keys. Never store structs in args.
• Security: no String.to_atom/1 with user input. Authorize in every LiveView handle_event. Never use raw/1 with untrusted content.
• OTP: no process without a runtime reason. Supervise all long-lived processes.
• Elixir: declare @external_resource for compile-time files. Wrap third-party library APIs behind project-owned modules. Never use assign_new for values refreshed every mount.

Ash First

Always use Ash concepts, almost never Ecto concepts directly. Think hard about the "Ash way" to do things. If you don't know, look for information in the rules & docs of Ash & associated packages.

When a change must remain atomic, implement atomic/3 or refactor the action to stay atomic. Do not use require_atomic? false to silence atomicity warnings.

Ash rebuilds atomic updates from a second changeset. Put compare-and-set filters on the pending caller changeset, not in an action-level change filter(...). When change/3 registers an after_action hook, atomic/3 must return {:ok, change(changeset, opts, context)} rather than bare :ok. In an atomic callback, read proposed values from changeset.atomics or Ash.Changeset.fetch_change/2; Ash.Changeset.get_attribute/2 can return old data or raise when original data is unavailable.

Database Schema Management

CRITICAL: All database schema changes (tables, views, indexes, materialized views, extensions) MUST be managed exclusively through Elixir migrations in elixir/serviceradar_core/priv/repo/migrations/.

CRITICAL: All tables, indexes, and constraints belong in the platform schema. Do not create or reference objects in the public schema. In migrations, set prefix: "platform" for new tables/indexes/constraints and avoid prefix: "public" in references.

Ingestion services must NEVER create database schema or run DDL statements. They write to existing tables but do not create or modify schema.

This rule exists because:

• Elixir migrations provide a single source of truth for schema
• Ecto migrations support up/down rollbacks and version tracking
• Having schema scattered across Go and Elixir creates maintenance nightmares
• Ingestion services may be replaced or scaled differently than schema management

If you need a new table, view, or materialized view that ingestion will write to, create the migration in Elixir first.