> ## 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 SILOC

> Operate Lerian SILOC: BACEN settlement windows, ICP-Brasil certificates, opt-in SFN ingestion, durable deduplication, monitoring, alerts, and audit.

SILOC settles on a **deferred-net, business-day** basis, and Lerian SILOC works within that one operational reality. The service keeps the gateway connection open and, when SFN ingestion is enabled, dispatches its supported messages. It holds no accounting position.

## Settlement windows

***

SILOC settles on a deferred multilateral net basis, on business days. Nuclea defines the daily settlement windows for boleto and card products. Lerian SILOC records and applies the transfer-order messages that open, advance, reconcile, and close its cycle state; it does not calculate the monetary net position.

## Regulated certificates

***

You register the gateway's certificates as a **public certificate plus an external custody reference**. The service holds no private key. When you register a certificate, the service parses its subject, serial, and validity window. You revoke the certificate over the API when you retire it. A **credential-disabled** state halts the gateway. A disabled or revoked certificate fail-closes the connection instead of running on invalid credentials.

## Contingency and recovery

***

The SFN ingestion path has defined outcomes under failure; it does not promise that every frame is retained or that every operation has a single end-to-end effect:

* SFN ingestion is opt-in. `SFN_INGEST_ENABLED` defaults to `false`; enable it explicitly before the consumer starts.
* An undecodable envelope, a decoded message without a nonblank `BCMSG.NUOp`, or an unsupported `CodMsg` — including `PAG0101` — bypasses normal dispatch. A non-retryable failure follows the dead-letter path and is acknowledged so the partition can progress.
* A retryable dispatch failure remains unacknowledged. With offset-safe source commits, it is read again after a restart from the last committed offset; a persistent transient failure can stall its partition until restart.
* Delivery and dispatch are **at-least-once**. For a successfully decoded and supported message, the service checks durable deduplication by **(`BCMSG.NUOp`, `CodMsg`)** before dispatch and writes the processed-message record only after dispatch succeeds. This is not message-ID-only deduplication and is not an unconditional end-to-end exactly-once guarantee.

## Reconciliation

***

Reconciliation runs at several grains so the connection's state never drifts:

* **Processed-message dedup ledger.** For successfully decoded and supported messages with a nonblank NUOp, the ledger uses the composite key (`BCMSG.NUOp`, `CodMsg`) and records it only after a successful dispatch. Undecoded and unsupported messages do not receive a processed-message record.
* **Message-processing audit feed.** The audit feed lists supported SFN messages that the service dispatched.
* **Per-participant status and status history.** Each participant carries its operational status. The service keeps every status change as a status-event history entry.

## Monitoring, alerts, and audit

***

Lerian SILOC exposes an operator surface for watching OT settlement cycles, connection and relay health, and participant status. The cycle and reconciliation surfaces report recorded state and reconciliation sets; they do not calculate aggregate position figures on read.

* **OT settlement cycles.** [`GET /api/v1/siloc/cycles`](/en/reference/rails/siloc/list-cycles) and [`GET /api/v1/siloc/cycles/{cycleId}`](/en/reference/rails/siloc/get-cycle) list and inspect cycles. [`GET /api/v1/siloc/cycles/{cycleId}/reconciliation`](/en/reference/rails/siloc/get-cycle-reconciliation) returns the reconciliation result, and [`GET /api/v1/siloc/cycles/{cycleId}/recalculations`](/en/reference/rails/siloc/get-cycle-recalculations) returns the cycle's recálculo round chain — including each round's complement/deposit window closure.
* **Settlement instructions.** [`GET /api/v1/siloc/settlement-instructions`](/en/reference/rails/siloc/list-settlement-instructions) and [`GET /api/v1/siloc/settlement-instructions/{instructionId}`](/en/reference/rails/siloc/get-settlement-instruction) return each cycle's obligation legs. [`POST /api/v1/siloc/rocs`](/en/reference/rails/siloc/ingest-roc) ingests a semantic ROC revision that supersedes prior values for the cycle.
* **Operational alerts.** [`GET /api/v1/siloc/alerts`](/en/reference/rails/siloc/list-alerts) returns an active-only, keyset-paged feed. Alert types include `WINDOW_CLOSING` (a deposit/complement deadline is approaching), `RECALCULATION` (a cycle is in a recálculo round), `RELAY_DOWN`, `CONNECTION_DOWN`, `CERTIFICATE_EXPIRY`, and `SCHEDULE_CHANGE` (an operator recorded a contingency schedule announcement). Alerts clear atomically when the underlying condition resolves — for example, a cycle that settles clears its `RECALCULATION` alert on the settle path. Pass `activeOnly=false` to include deactivated alerts as history.
* **Audit trail.** [`GET /api/v1/siloc/audit-records`](/en/reference/rails/siloc/list-audit-records) returns a paged, verbatim read of the audit trail — for example, to export the record of an operator action or a participant status change. Bounds `from` and `to` are RFC3339 instants (date-only values are rejected).

## Schedule and contingency

***

The OT cycle grid and business-day calendar are compiled artifacts on the service — the API projects them verbatim; it never parses a Núclea schedule wire.

* **Calendar and windows.** [`GET /api/v1/siloc/schedule/calendar`](/en/reference/rails/siloc/get-business-day-calendar) returns the business-day calendar, and [`GET /api/v1/siloc/schedule/windows`](/en/reference/rails/siloc/list-schedule-windows) returns the compiled canonical OT window grid — a static artifact, not a per-day read, served even when the datastore is down.
* **Contingency schedule changes.** [`POST /api/v1/siloc/schedule/changes`](/en/reference/rails/siloc/record-schedule-change) records a contingency announcement the operator received out of band from Núclea. The body carries `reason` (≤500 chars), `origin` — the announcing channel or upstream reference (≤256 chars) — `effectiveAt`, the announced RFC 3339 instant the change takes effect, and an optional `windowSeq` naming the affected canonical window. The record is **append-only**: a later announcement never rewrites an earlier one. The newest announcement does become the single active `SCHEDULE_CHANGE` alert — recording one clears the prior alert and raises a new one whose deadline is `effectiveAt` verbatim. [`GET /api/v1/siloc/schedule/changes`](/en/reference/rails/siloc/list-schedule-changes) returns the recorded changes, newest first.

Record a contingency schedule change:

```bash theme={null}
curl -X POST https://siloc.example.com/api/v1/siloc/schedule/changes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Núclea extended the OT window by 30 minutes",
    "origin": "Núclea e-mail ref 2026-07-22/01",
    "effectiveAt": "2026-07-22T18:30:00-03:00",
    "windowSeq": 2
  }'
```