> ## 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. The panel never offers an action that the rail refuses. Every verb carries a mandatory operator justification. The rail stores that justification with the outcome.

A return that never received an answer has its own exit. A `pacs.004` with no status reply leaves the return in an indefinite wait. The return holds sum-ceiling headroom that the Pix can never reuse. On the full-return surface, it blocks 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. The release of a ceiling on a return with an unknown outcome is how one Pix gets two returns. An unproven return stays where it is, and the rail does not offer the release.

## 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 active. 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. The rail records an inbound `pacs.008` as pending. The authenticated client's funding decision then completes or refuses it. The same holds for a return: BACEN's answer concludes a `pacs.004` the rail accepted for dispatch. The send never concludes it.
* **A return's identity is recorded, not derived.** The rail stores which surface created a return. 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.