@callback delete_by_chunks(chunk_ids :: [binary()], opts :: keyword()) ::
  :ok | {:error, term()}

Deletes all graph data for the given chunk IDs.

Removes mentions referencing these chunks, then sweeps entities the deletion orphaned. The sweep is scoped to the collections those chunks belonged to, so deleting in one tenant leaves every other tenant's graph alone.

Prefer Arcana.delete/2, which removes the document and its chunks and sweeps in one step. Reach for this only when you are deleting chunks yourself.

The call is not atomic

In the Ecto backend the mention delete and the per-collection sweeps are separate transactions: the collections to sweep aren't known until the delete says which entities it touched, and a collection can't be locked before it has been identified. A crash or a dropped connection between them commits the delete and skips the rest, leaving entities with no mentions behind.

Nothing is lost and nothing is wrongly retained: an entity with no mentions is exactly what a sweep collects, and every sweep is idempotent, so the next one over that collection finishes the job. Those run from Arcana.delete/2 (through maybe_sweep_orphans/3), after a replace: true ingest, and from the dashboard's maintenance page, which also reports the outstanding orphan count.

The memory backend has no such window, since the whole operation is one GenServer call.

@callback delete_by_collection(binary(), opts :: keyword()) :: :ok | {:error, term()}

Deletes all graph data for a collection.

Removes all entities, relationships, mentions, and communities associated with the collection.

@callback find_entities(binary(), opts :: keyword()) :: [map()]

Finds all entities in a collection.

@callback find_related_entities(binary(), depth :: pos_integer(), opts :: keyword()) :: [
  map()
]

Finds entities related to the given entity within the specified depth.

Enables graph-native traversal operations.

@callback get_community(community_id :: binary(), opts :: keyword()) ::
  {:ok, map()} | {:error, :not_found}

Retrieves a single community by ID.

@callback get_community_summaries(binary(), opts :: keyword()) :: [map()]

Retrieves community summaries for a collection.

@callback get_entity(binary(), opts :: keyword()) :: {:ok, map()} | {:error, :not_found}

Retrieves a single entity by ID.

@callback get_mentions(binary(), opts :: keyword()) :: [map()]

Retrieves mentions for an entity with chunk context.

Returns mentions with associated chunk text for display.

@callback get_relationship(relationship_id :: binary(), opts :: keyword()) ::
  {:ok, map()} | {:error, :not_found}

Retrieves a single relationship by ID.

@callback get_relationships(binary(), opts :: keyword()) :: [map()]

Retrieves all relationships for an entity.

Returns relationships where the entity is either source or target.

@callback list_communities(opts :: keyword()) :: [map()]

Lists communities with optional filtering and pagination.

Options

• :collection_id - Filter by collection (nil for all)
• :level - Filter by hierarchy level
• :search - Search in summary
• :limit - Maximum results (default: 50)
• :offset - Pagination offset (default: 0)

Returns communities with entity counts.

@callback list_entities(opts :: keyword()) :: [map()]

Lists entities with optional filtering and pagination.

Options

• :collection_id - Filter by collection (nil for all)
• :type - Filter by entity type
• :search - Search in entity name
• :limit - Maximum results (default: 50)
• :offset - Pagination offset (default: 0)

Returns entities with aggregated counts (mention_count, relationship_count).

@callback list_relationships(opts :: keyword()) :: [map()]

Lists relationships with optional filtering and pagination.

Options

• :collection_id - Filter by collection (nil for all)
• :type - Filter by relationship type
• :search - Search in entity names or type
• :strength - Filter by strength (:strong, :medium, :weak)
• :limit - Maximum results (default: 50)
• :offset - Pagination offset (default: 0)

Returns relationships with source/target entity names.

@callback persist_communities(binary(), [map()], opts :: keyword()) ::
  :ok | {:error, term()}

Persists community data for a collection.

@callback persist_entities(binary(), [map()], opts :: keyword()) ::
  {:ok, map()} | {:error, term()}

Persists entities to the graph store.

Returns a map of entity names to their assigned IDs.

@callback persist_mentions([map()], map(), opts :: keyword()) :: :ok | {:error, term()}

Persists entity mentions (links between entities and chunks).

@callback persist_relationships([map()], map(), opts :: keyword()) ::
  :ok | {:error, term()}

Persists relationships between entities.

@callback search([String.t()], [binary()] | nil, opts :: keyword()) :: [map()]

Searches for chunks related to the given entity names.

Returns scored chunk results.

@callback search_by_embedding([float()], [binary()] | nil, opts :: keyword()) :: [map()]

Searches for entities by embedding similarity.

Returns entities whose description embeddings are most similar to the query embedding, sorted by similarity descending.

@callback sweep_orphans(binary(), opts :: keyword()) :: :ok | {:error, term()}

Sweeps orphaned graph data in a collection.

Deletes entities in the collection that have no remaining mentions (their relationships cascade away), and marks communities whose entity_ids overlap the deleted entities as dirty so the next summarize pass regenerates them.

Intended to run after document deletion or replacement, scoped to the affected collection.

Optional. A store that doesn't implement it simply doesn't sweep: Arcana.delete/2 and the replace: true ingest still succeed, and the collection may keep entities with zero mentions — which is exactly how both paths behaved before this callback existed.

Serialization

A sweep must not interleave with a graph build for the same collection: a build inserts an entity before its mentions, so a sweep landing in that window would delete an entity that is about to be referenced.

The :ecto backend serializes both sides through with_write_lock/3 (a transaction-scoped Postgres advisory lock keyed on the collection). The :memory backend serializes individual calls through its GenServer but leaves the window between the entity and mention calls open, which is fine for a test backend. Custom backends get the full guarantee only if they implement with_write_lock/3.

@callback with_write_lock(binary(), opts :: keyword(), (-> result)) :: result
when result: term()

Runs fun while holding the collection's graph write lock.

Optional. Backends that can serialize concurrent graph writes implement this so sweep_orphans/2 and the entity/mention persist path cannot interleave. Backends that don't implement it simply run fun.

The lock is meant to cover DB writes only, never extraction, so callers keep the wrapped work short.

Guarantees

The contract is mutual exclusion per collection, nothing more. Atomicity is best-effort and store-dependent: callers must not assume that a failure inside fun rolls back the writes it already made.

The :ecto backend does give both, because it takes the advisory lock inside a transaction. The :memory backend implements neither (it falls through to running fun), so a mid-fun failure leaves partial graph data behind, which is fine for a test backend.

A custom store that wants the full guarantee has to do what the :ecto backend does: hold a per-collection exclusive lock and run fun inside a transaction that rolls back on failure, releasing the lock when the transaction ends. Doing only one of the two is worse than doing neither, since it reads as if both were covered.