> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Operating Lerian SPI

> Operating Lerian SPI: around-the-clock Pix settlement, certificate rotation, stuck-operation recovery, and DICT reconciliation grains.

Lerian SPI works around two operational realities of Pix. Pix settles in real time, 24 hours a day, and BACEN confirms every settlement asynchronously. The return dispatcher attempts to record an outbound `pacs.004` before submitting it, but a recording failure is best-effort and does not necessarily block dispatch.

## Around-the-clock settlement

***

Pix settles individually and instantly, around the clock. There is no daily window to open or close. Two adjacent surfaces use their own reference periods instead. Pix Automático scheduling (agendamento) gives each instruction a requested execution time and a last date it can settle. Conta PI reports use a balance or extract reference period, with a date window of up to 92 days.

## Certificate rotation

***

The rail manages the Pix signing certificate through its lifecycle. You upload the public `.cer`. You deactivate a certificate you retire. The rail rejects an uploaded private key, fail-closed. The rail stores only SHA-256 fingerprints and public metadata, so a response never exposes key material. The rail emits a days-until-expiry signal, so operators can act before a certificate expires.

## Contingency and recovery

***

When a payment gets stuck, the rail exposes only the actions it can perform:

* A **stuck-operations** view lists items that need attention.
* A **recovery-eligibility** evaluation decides whether an operation is recoverable.
* A **recovery action** or **manual resolution** clears an eligible operation.
* A **manual-authorization approvals** workflow gates operations that need an explicit sign-off before they proceed.
* An **evidence-export** job packages the record of an operation for audit or dispute.

The listing declares, per row, which verbs the rail can actually perform on it. A verb the rail cannot perform on a row is absent from that row, so the panel never offers an action that will be refused. Every verb carries a mandatory operator justification, which is persisted with the outcome.

A return that never received an answer has its own exit. A `pacs.004` with no status reply leaves the return waiting indefinitely, holding sum-ceiling headroom the Pix can never reuse and — on the full-return surface — blocking any further return of that Pix. An operator resolves such a return as not-realized, and the rail then frees the headroom it held.

The rail refuses that resolution unless its own state proves the money never left. Releasing the ceiling of a return whose outcome is unknown is how a Pix gets returned twice, so an unproven return stays where it is and the release is not offered.

## Reconciliation

***

Reconciliation capabilities operate at several grains. Automatic incremental and full DICT reconciliation run only when `SCHEDULER_ENABLED=true` and their respective feature gates are enabled, and a run can fail. Orphaned-key cleanup and claim-deadline processing are separate flows:

* **DICT reconciliation** can run full or from BACEN's event list.
* **Orphaned-key cleanup** can remove keys an interrupted flow left behind.
* **Claim-deadline processing** can advance or close claims against their BACEN windows.

## Settlement invariants

***

Three invariants hold throughout:

* **A submit is dispatch, not confirmation.** An accepted submit confirms only that the rail accepted the dispatch. For an outbound payment, the inbound `pacs.002` status reply applies `COMPLETED` or `REJECTED` and projects BACEN's fields verbatim. An inbound `pacs.008` is recorded pending and is completed or refused by the authenticated client's funding decision. The same holds for a return: a `pacs.004` the rail accepted for dispatch is concluded by BACEN's answer, never by the send.
* **A return's identity is recorded, not derived.** The rail stores which surface created a return, so a partial return keyed by a client-chosen identifier is never read as the full return of its Pix.
* **The rail is money-neutral.** It forwards declared amounts exactly and computes no position or balance. Your ledger consumer records any accounting position.