gno

# GEMINI.md - Gno Project Context

## Project Overview

Gno is an Elixir library that abstracts RDF dataset persistence across different storage backends, providing a unified API for managing RDF data in SPARQL triple stores. It is built on [DCAT-R](https://w3id.org/dcatr) for its structural model and serves as a foundation for higher-level systems like Ontogen.

### Key Features
- **Unified API**: Consistent interface for SPARQL queries (SELECT, ASK, CONSTRUCT, DESCRIBE) and updates (INSERT, DELETE, DATA operations).
- **Manifest System**: RDF-based configuration (Turtle files) for environment-specific service and store setups.
- **Changeset System**: Structured representation of RDF graph changes (add, update, replace, remove) with minimal effective change computation.
- **Commit System**: Transactional change application with a middleware pipeline (validation, logging, metadata) and automatic rollback support.
- **Store Adapters**: Pluggable backend support, including Apache Jena Fuseki, Oxigraph, and GraphDB.

## Architecture

1.  **Gno.Service**: The central entry point linking a `DCATR.Repository`, a `Gno.Store`, and commit operations.
2.  **Gno.Manifest**: Configuration system loading RDF definitions from `config/gno/`.
3.  **Gno.Changeset / Gno.EffectiveChangeset**: Functional representation of graph modifications.
4.  **Gno.Commit.Processor**: State machine managing the lifecycle of a commit.
5.  **Gno.Store.Adapter**: Behaviour for implementing specific SPARQL store interactions.

## Development Lifecycle

### Building and Running
```bash
# Install dependencies
mix deps.get

# Compile the project
mix compile

# Run all tests
mix test

# Run code formatter
mix format

# Run static analysis
mix dialyzer

# Generate documentation
mix docs
```

### Store Backend Setup for Testing
Tests require a running SPARQL store. Default test configuration often uses Fuseki.
- Fuseki setup: `curl -X POST http://localhost:3030/$/datasets -d "dbType=mem&dbName=gno-test-dataset" -H "Content-Type: application/x-www-form-urlencoded"`

## Engineering Standards

### Conventions & Style
- **Elixir Idioms**: Follow standard Elixir patterns and maintain code formatting via `mix format`.
- **Error Handling**: Prefer `{:ok, result}` or `{:error, %ExceptionStruct{}}`. Use exception structs (defined in `lib/gno/exceptions.ex`) for detailed error information.
- **Bang Variants**: Provide `function!/n` variants that raise exceptions for all major API functions.
- **Grax Integration**: Use `Grax` for mapping RDF data to Elixir structs.

### Testing Practices
- **Testing Approach**: "Exact-First Testing" - prefer `==` with complete structs, then pattern matching, then field assertions.
- **Test Support**: Use `GnoCase` for common setup and `Gno.TestFactories` for data generation.
- **Coverage**: Maintain high test coverage (threshold set to 84% in `mix.exs`). Run with `mix test --cover`.

### Documentation
- Document "why" rather than "what".
- Use `## Options` for function options and `## Examples` with doctests when possible.
- Keep moduledocs focused and concise.

## Key Files & Directories
- `lib/gno.ex`: Primary public API.
- `lib/gno/manifest/manifest.ex`: Configuration entry point.
- `lib/gno/changeset/changeset.ex`: Core changeset logic.
- `lib/gno/commit/processor.ex`: Commit state machine.
- `lib/gno/store/adapter.ex`: Store adapter behaviour.
- `priv/vocabs/gno.ttl`: Gno's RDF vocabulary.
- `magma/kb/gno-concept-paper.md`: High-level architecture and concepts.