@spec allow(table(), pid(), pid()) :: :ok

Authorise child_pid to inherit overrides from owner_pid.

Use this for long-lived processes (GenServers, Oban workers, Tasks spawned outside the $callers chain) that need to read the test's overrides. Mirrors Ecto.Adapters.SQL.Sandbox.allow/3.

@spec delete(table(), key()) :: :ok

Remove the current process's override for key. No-op if absent, if the table doesn't exist, or if overrides aren't compiled in – teardown helpers stay safe to call unconditionally.

@spec delete_all(table()) :: :ok

Remove every override the calling process owns in table. Same no-op guarantees as delete/2 – safe on an unknown table or a disabled build.

Does not touch allow grants or the table's mode; use set_private/1 for the latter.

@spec enabled?() :: boolean()

Whether the override machinery was compiled into this build.

false unless the consuming app opted the env in. When false, put/3, allow/3, Server.start_link/1 and Server.init/1 all refuse, so no Ambient API can create a table or an override – see the moduledoc for the one thing that is still possible, and why.

Intended for compile-time branching – put it in a module body:

if Ambient.ProcessOverride.enabled?() do
  def helper, do: :test_only
else
  def helper, do: :real
end

Branching on it at runtime is harmless but pointless: the value is fixed when Ambient is compiled, so one arm is simply dead code.

@spec fetch(table(), key()) :: {:ok, value()} | :error

Fetch the override in effect for the calling process.

In private mode (the default) that means the lookup chain self → allow → $callers; in shared mode it is always the shared owner's value, whoever asks. Returns :error if no override is in effect – including when the table doesn't exist, which is every build that didn't opt in, since nothing there can create one.

Deliberately not compiled away in disabled builds: a clause hard-wired to :error makes every caller's {:ok, _} branch provably dead, and the compiler reports those as warnings in consuming apps. The cost of keeping it is a single :ets.whereis/1.

@spec get_and_update(table(), key(), (value() -> {result, value()})) ::
  {:ok, result} | :error
when result: term()

Atomically read the value for key, run fun over it, and store the result. Returns {:ok, value} where value is fun's first element, or :error if no override is in scope.

For values whose reads write: a counter that hands out the next id, a budget that decrements. A plain fetch/2 then put/3 is fine in private mode, where each process owns its own row, but in shared mode every process is reading and writing the same row – so two concurrent reads see the same state, compute the same result and overwrite each other. Measured before this existed: 99 lost updates in 200 concurrent reads, i.e. half the callers got a duplicate.

In shared mode the whole read-modify-write therefore happens inside the Server, which serialises it. Private mode stays client-side, since a process can't race itself.

If fun raises (or returns something other than a two-tuple), the exception surfaces in the caller in both modes. In shared mode it is caught inside the Server and re-raised here, because letting it escape there would take the table owner down with it and void every override in the table – so the stacktrace is the one captured Server-side. A raise inside fun keeps its own frame; the MatchError for a malformed return is reported against the Server. Private mode runs client-side and is unaffected.

Note what this does not buy: which concurrent caller gets which value still depends on scheduling. One advancing stream and reproducible ordering are mutually exclusive under concurrency.

@spec mode(table()) :: :private | {:shared, pid()}

Report whether table is process-scoped or globally shared.

Returns :private for an unknown table, so it is safe to call anywhere.

@spec put(table(), key(), value()) :: :ok

Store a process-local override. The key lets one table host multiple keys per owner (e.g. config). Pass a sentinel like :clock for single-value-per-owner tables.

The current process is monitored – its rows clear automatically on exit.

@spec server_name(table()) :: atom()

Compute the registered name of the Server instance that owns table. Public so the Server can register itself under the same name put/3 calls.

@spec set_private(table()) :: :ok

Return table to private (process-scoped) mode. Idempotent, and a no-op if the table was never shared. Existing overrides are left alone – they simply resolve per process again.

Deliberately callable by any process, unlike the other writers: it is the way back to a sane state, and ExUnit's on_exit/1 runs in a different process from the test that took the table shared.

@spec set_shared(table(), pid()) :: :ok

Switch table to shared mode: owner_pid's overrides become the ones every process reads, no matter how it was spawned.

For async: false tests only – it is global state, exactly like Ecto.Adapters.SQL.Sandbox's shared mode or Mox.set_mox_global/0. A concurrent test would see the shared owner's clock.

While shared, only owner_pid may write to the table (put/3 from anyone else raises {:not_shared_owner, pid}) and allow/3 is refused – every process already reads the owner's values, so there is nothing to grant. get_and_update/3 is the exception, so read-modify-write values keep working – atomically – from every process.

Handing over to a different owner is the current owner's call: once shared, set_shared/2 from anyone else raises {:not_shared_owner, pid} rather than silently stealing the table.

The owner is monitored: if it exits, the table drops back to private mode on its own, so a crashed test can't leave the suite globally overridden.