# Arcadic v0.1.0 - Table of Contents

> A lean, framework-agnostic Elixir client for ArcadeDB over the HTTP Cypher command API.

## Pages

- [Arcadic](readme.md)
- [Getting started with Arcadic](getting_started.md)
- [arcadic usage rules](usage-rules.md)
- [Changelog](changelog.md)
- [Contributing to Arcadic](contributing.md)
- [LICENSE](license.md)

## Modules

- [Arcadic](Arcadic.md): A lean, framework-agnostic Elixir client for [ArcadeDB](https://arcadedb.com)
over the **HTTP Cypher command API**.
- [Arcadic.Conn](Arcadic.Conn.md): Connection handle for ArcadeDB — pure data, no process.
- [Arcadic.Identifier](Arcadic.Identifier.md): Allowlist validation for identifiers arcadic places into a URL path or a
statement (database names, labels, property names).
- [Arcadic.Migration](Arcadic.Migration.md): Behaviour for an ArcadeDB migration — a versioned pair of forward/backward steps.
Migrations are tenant-blind schema changes; author raw DDL/DML via `Arcadic.command/4`
in `up/1` and `down/1`.
- [Arcadic.MigrationRegistry](Arcadic.MigrationRegistry.md): Declares an ordered list of migration modules.
- [Arcadic.Migrator](Arcadic.Migrator.md): Runs `Arcadic.Migration`s in order and tracks applied versions in the
`_arcadic_migrations` document type. Tenant-blind: it runs DDL/DML and records
integer versions — no tenant, scope, or Ash concept. Assumes single-process,
deploy-time execution (like every migration tool); it does not take an advisory
lock, so do not run two migrators concurrently against one database.

- [Arcadic.Result](Arcadic.Result.md): Normalizes an ArcadeDB command/query response envelope into a list of rows.
- [Arcadic.Server](Arcadic.Server.md): Server-level admin: create/drop/list databases, existence, readiness. Every
identifier is allowlist-validated BEFORE any request reaches the wire (fixes the
interpolation surface a hand-written `create database <name>` would open). Returns
are tagged tuples — a transport failure is never swallowed into a bare boolean.
Not delegated from the `Arcadic` facade: destructive admin stays namespaced.

- [Arcadic.Telemetry](Arcadic.Telemetry.md): Value-free `:telemetry.span/3` wrapper. Owns the metadata allowlist — the single
enforcement point for "no statement text, no params, no values, and NO database
name" (the DB name is the tenant/mode selector upstream; tenant-blind includes
telemetry). An off-allowlist key raises rather than shipping identity downstream.
Mirrors `ash_age`'s R7 allowlist pattern.

- [Arcadic.Transaction](Arcadic.Transaction.md): Session transactions. `transaction/3` begins a session, runs the fun with a
session-scoped conn, and commits on a normal return. On an exception it rolls
back and RERAISES (postgrex semantics — unexpected failures propagate, they do
not become `{:error, …}`). Use `rollback/2` for an intentional abort that yields
`{:error, reason}`. Nesting raises — there is no verified HTTP savepoint contract.

- [Arcadic.Transport](Arcadic.Transport.md): The transport seam (charter D2). One implementation ships — `Arcadic.Transport.HTTP`
(Req/Finch). A future Bolt adapter implements the same callbacks. Callbacks are
SEMANTIC (mode/session), not HTTP-verb-shaped, so a non-HTTP transport can honor
them. This behaviour is also the mock seam consumed by `ash_arcadic`'s tests.
- [Arcadic.Transport.Bolt](Arcadic.Transport.Bolt.md): Bolt transport for ArcadeDB via the `boltx` driver (Bolt v4). Verified interop
(spec §15 P19/P20). The consumer starts a Bolt connection with `start_link/1`
(which encodes the ArcadeDB-correct defaults — Bolt v4 pin, non-TLS scheme) and
passes it as `transport_options: [bolt: conn_ref]`.
- [Arcadic.Transport.HTTP](Arcadic.Transport.HTTP.md): The HTTP Cypher transport (the only implementation of `Arcadic.Transport`).

- Exceptions
  - [Arcadic.Error](Arcadic.Error.md): A server-returned ArcadeDB error, normalized to a typed `reason`.
  - [Arcadic.TransportError](Arcadic.TransportError.md): A transport/network failure with no HTTP response (connection refused, timeout,
closed). `reason` is the underlying Mint/Finch reason atom — value-free.

