# Design

_Why is Mediate shaped this way, and what did it reject? For a reader who wants to change the shape._

Each entry is one decision, the alternative it rejected, and why. The moduledocs say what each thing does, and `docs/conformance.md` says what a test asserts.

## What the library is not

- **The library emits records and stores nothing.** A store in a library package, a table or a log, was the alternative. A consumer attaches a handler and owns the record, so retention, protection, and review of the record are the deployer's.
- **The seam is not a reference monitor.** A claim that every access passes through it was the alternative. The seam sees repo calls and nothing else, and no control in the baseline asks for a reference monitor.
- **Each tool enforces what it can see.** The seam sees repo calls, the database sees rows, and a Credo check sees source. One tool that claims the others' ground was the alternative, and no test can hold it to that claim.
- **The port is minimal by a measure.** It carries what the example application needs plus what the conformance laws need. A port that anticipates a need was the alternative, and what neither reaches goes.

## The port

- **Four functions, and no fifth.** A policy language of the library's own was the alternative. The mechanism belongs to the adapter, and the port belongs to the application.
- **A decision is a struct the seam accepts.** A boolean was the alternative. A boolean cannot carry the id, the version, and the subject the repo call must log under.
- **`scope` returns a `dynamic` that can only narrow.** A query the adapter builds was the alternative. A fragment the caller adds to a query it wrote cannot widen the query, and the scope-fidelity law holds the fragment to what `check` says.
- **`review` asks `scope` once per subject under the reviewer's operation id.** A review callback on the adapter was the alternative. An adapter that binds the subject at query time answers a review through the same callback, and the reviewer's own decision joins the subjects' under one id.
- **Deny by default, fail closed.** The port denies an operation no rule names, and denies when the adapter raises or reports its engine unreachable. An engine error passed to the caller was the alternative, and a caller that forgets to handle it allows.
- **A bad call raises, and a bad answer denies.** An option that fails validation and a configuration that never booted are programmer errors, so they raise before the adapter runs. The decision event still fires, with `verdict: nil` and the exception, so no call goes unrecorded.
- **The vocabulary is NIST SP 800-162's.** Subject, object, operation, and environment. Actor, resource, action, and context were the alternative, and the assessor reads 800-162.
- **Three subject kinds, refused before any adapter runs.** A free atom was the alternative. A fixed list is what lets a decision event say that a privileged function ran.
- **The environment is a map the caller fills, with `now` stamped from the configured clock.** A clock in each adapter was the alternative. One clock lets a test set the moment and lets every adapter agree on it.

## The seam

- **A mediated repo refuses a call that carries no decision and no exemption.** A mode that logs and does not raise was the alternative. An unmediated call is an unlogged access, and a log a flag can silence is not complete.
- **The refusal raises.** An error value was the alternative. An unmediated call is a programmer error, and a correct program never reaches it on the request path.
- **The seam judges the root source.** Judging every joined source was the alternative. The root's decision covers the associations the schema declares with `carries/1`, and a joined source it does not carry fails the query.
- **A bulk write to an audited schema is refused.** An event per row was the alternative. One statement that changes many rows gives the seam no old value, and an event built from a guess is not a record.
- **An upsert on a fact schema is refused.** A change event that says insert or update was the alternative. `RETURNING` cannot say which rows were inserts and which were updates.
- **Exemptions are named and recorded.** A silent bypass was the alternative. A declared exemption carries a reason and the caller. The owner-role repo needs none, because it is the library's own channel and records nothing.
- **Declarations live on the schema.** A registry module was the alternative. `use Mediate.Schema` compiles each declaration to a clause of `__mediate__/1`, so the seam and every adapter read one source.
- **An adapter extends the seam through `around_query/3`.** A hook per bucket was the alternative. One wrap around every mediated call is what row-level security needs to bind session settings, and no other adapter needs more.

## The events

- **Three events on the request path, and one per adapter for a policy version.** One event with a kind field was the alternative. Three payloads with fixed fields let a consumer map each to its own record class without a branch.
- **The change event fires inside the write's transaction.** After commit was the alternative. Inside it, a consumer that writes to the same repository joins the transaction, and the record and the row commit together or not at all.
- **The access event fires after the read returns.** Before was the alternative, and the event carries the ids the read returned.
- **No payload carries a class, category, or severity identifier.** A payload that is an OCSF record was the alternative. Those identifiers move between schema versions and belong to the consumer.
- **No payload carries a value the rule read from the world.** The clearance and the marking in the event were the alternative. The controls ask for a record of the question and the answer, and an attribute value in the log is a second copy of a fact.
- **A policy version carries the policy text by value under a cap, and a pointer above it.** Text always, or a pointer always, were the alternatives. A reviewer reads a small policy in the event and a large one where it lives.

## Packages and dependencies

- **One package per adapter.** One package with optional dependencies was the alternative. An adopter of one mechanism carries no other mechanism's dependencies.
- **`mediate` has three runtime dependencies, and a test holds the count.** The conformance suites are a package of their own, which an adapter author takes in the test environment. The suites in `mediate` was the alternative, and then an application that calls the port installs and starts a property-testing library.
- **The test tools are an unpublished package.** The cluster and the engine launchers in `mediate` was the alternative. A launcher starts an OS process, and an adapter package carries no dependency its users do not need.
- **A sibling binds by path in a checkout of this repository and by requirement everywhere else.** `in_umbrella: true` in the published `mix.exs` was the alternative, and Hex moves such a dependency to the excluded list, so the package reaches an adopter naming none of its siblings. `flake.nix` exports `MEDIATE_UMBRELLA`, each published `mix.exs` reads it, and `mix mediate.package` builds with it removed.
- **Three interior places under each root.** A free layout was the alternative. `CONTRIBUTING.md` names the places, and the structure test enforces them.
- **Library packages ship migration helpers, and only thin applications carry migrations.** An adapter package that carries the example's migrations names the example's domain, and an adapter is domain-free.
- **Behaviours, not protocols.** A behaviour's `behaviour_info/1` enumerates its surface, and `function_exported?/3` answers an optional callback at runtime. One build then serves every adapter.

## Configuration

- **Boot validates one struct and stores it in `:persistent_term`.** A read of `Application.get_env` at each call was the alternative. One validated read at boot means no call on the request path finds a bad value.
- **A test overrides through the process dictionary, and the resolver walks `$callers`.** `Application.put_env` in tests was the alternative, and it serializes every test.
- **An adapter validates its own options through `options_schema/0`.** A schema per adapter inside `mediate` was the alternative, and it names each adapter in the core.

## What a test may claim

- **The surface is what a test can assert.** A guarantee no test can reach is not a guarantee this repository makes.
- **A decision lives in a module that a test can call directly.** A module that touches the world does nothing else.
- **Every adapter passes the same laws against its real engine.** A fake engine was the alternative, and a fake proves the fake.
- **Each law carries the controls it answers, as data.** A mapping kept by hand was the alternative. The freeze test holds the table to `docs/conformance.md` row for row.
- **Latency is printed and never asserted.** An asserted number flaps, and a number no test asserts has no home in a document.
- **Shape tests count queries and events, never time.** Counts are exact in the sandbox and cannot flap.

## What changes a decision

- A team asks for replay: a consumer that stores change events is the adopter's to write, outside this repository.
- A package passes eighty modules: the structure test grows a rule before the shape goes.
- The application wants durable audit at low volume: a consumer over Oban, still the adopter's.
- No test can show the seam covers some repo call: the enforcement moves to the data layer, as the Postgres adapter already does for writes.