# `Gno.Commit.Processor`
[🔗](https://github.com/rdf-elixir/gno/blob/v0.1.0/lib/gno/commit/processor.ex#L1)

State machine orchestrating the execution of a commit operation.

The processor drives a `Gno.Changeset` through a multi-phase pipeline —
pre-commit, transaction, post-commit — with automatic rollback on failure.
At each state transition, the configured `Gno.CommitMiddleware` pipeline is
invoked, and the actual step logic is delegated to the `Gno.CommitOperation.Type`.

## Phases

- **Pre-commit**: Initializes the changeset from input, computes the
  `Gno.EffectiveChangeset`, and prepares metadata (e.g. the `Gno.Commit`).
- **Transaction**: Starts a SPARQL transaction, applies the changes, and
  commits the transaction. Failures in this phase trigger a rollback.
- **Post-commit**: Runs finalization logic. Failures here do **not** roll back
  (the transaction is already committed).

## Struct Fields

- `service` - the `Gno.Service` this processor operates on
- `state` - the current `t:state/0` in the state machine
- `input` - the raw input passed to `execute/3`
- `input_options` - options passed to `execute/3`
- `middlewares` - the list of `Gno.CommitMiddleware` instances
- `changeset` - the `Gno.Changeset` created from the input
- `effective_changeset` - the `Gno.EffectiveChangeset` computed during preparation
- `sparql_update` - the `Gno.Store.SPARQL.Operation` built from the effective changeset
- `additional_changes` - extra changes for specific graphs, keyed by graph name
- `metadata` - an `RDF.Graph` accumulating commit metadata (PROV vocabulary)
- `assigns` - a free-form map for sharing state between middlewares
- `errors` - accumulated errors during processing

## State Machine

```mermaid
stateDiagram-v2
  [*] --> initializing : init

  %% Pre-Commit Phase
  initializing --> initialized : success
  initializing --> middleware_rollback: fail
  initialized --> preparing : success -> prepare
  initialized --> middleware_rollback: fail
  preparing --> prepared: success
  preparing --> middleware_rollback: fail
  prepared --> starting_transaction: success -> start_transaction
  prepared --> middleware_rollback: fail

  %% Transaction Phase
  starting_transaction --> transaction_started: success
  starting_transaction --> middleware_rollback: fail
  transaction_started --> applying_changes: success -> apply_changes
  transaction_started --> middleware_rollback: fail
  applying_changes --> changes_applied: success
  applying_changes --> middleware_rollback: fail
  changes_applied --> ending_transaction: success -> end_transaction
  changes_applied --> rollback: fail
  ending_transaction --> transaction_ended: success
  ending_transaction --> rollback: fail

  %% Post-Commit Phase
  transaction_ended --> executing_post_commit: success -> post_commit
  transaction_ended --> rollback: fail
  executing_post_commit --> completed: success
  executing_post_commit --> error: fail
  completed --> [*]

  %% Rollback Phase
  rollback --> middleware_rollback: success
  rollback --> critical_error: fail
  middleware_rollback --> error: success
  middleware_rollback --> critical_error: fail

  %% Error States
  error --> [*]
  critical_error --> [*]

  state pre-commit {
      initializing
      initialized
      preparing
      prepared
  }
  state commit-transaction {
      starting_transaction
      transaction_started
      applying_changes
      changes_applied
      ending_transaction
      transaction_ended
  }
  state post-commit {
      executing_post_commit
      completed
  }
```

# `assigns`

```elixir
@type assigns() :: %{optional(atom()) => any()}
```

# `state`

```elixir
@type state() ::
  nil
  | :initializing
  | :initialized
  | :preparing
  | :prepared
  | :starting_transaction
  | :transaction_started
  | :applying_changes
  | :changes_applied
  | :ending_transaction
  | :transaction_ended
  | :executing_post_commit
  | :completed
  | :rollback
```

# `t`

```elixir
@type t() :: %Gno.Commit.Processor{
  additional_changes: %{optional(atom()) => any()},
  assigns: assigns(),
  changeset: Gno.Changeset.t(),
  effective_changeset: Gno.EffectiveChangeset.t(),
  errors: [any()],
  input: any(),
  input_options: keyword(),
  metadata: RDF.Graph.t(),
  middlewares: [Gno.CommitMiddleware.t()],
  service: Gno.Service.t(),
  sparql_update: Gno.Store.SPARQL.Operation.t(),
  state: state()
}
```

# `add_error`

Adds an error to the processor's error list.

# `add_metadata`

Adds RDF statements to the processor's metadata graph.

# `all_changes`

Returns the complete set of changes to apply, including additional changes.

Delegates to the `Gno.CommitOperation.Type` implementation.

# `assign`

Stores a key-value pair in the processor's assigns map.

Assigns provide shared state between middlewares during a commit.

# `commit_id`

Returns the commit ID from the processor assigns.

# `execute`

Executes the commit pipeline with the given input changes and options.

Runs through pre-commit, transaction, and post-commit phases as described
in the module documentation. Returns `{:ok, commit, processor}` on success.

# `new`

Creates a new processor for the given `Gno.Service`.

# `new!`

# `operation`

Returns the `Gno.CommitOperation` struct for this processor.

# `operation_type`

Returns the `Gno.CommitOperation.Type` module for this processor.

# `set_commit_id`

Sets the commit ID, optionally renaming it in existing metadata.

When `update_metadata?` is `true` (default), renames any existing commit ID
references in the metadata graph.

# `update_metadata`

Replaces the processor's metadata graph, or applies a function to it.

Accepts either an `RDF.Graph` or a function `(RDF.Graph -> RDF.Graph | {:ok, RDF.Graph} | {:error, term})`.

# `update_metadata!`

---

*Consult [api-reference.md](api-reference.md) for complete listing*