Reference / Operations
Recover from durable evidence, not from assumptions.
Stargazer treats the raw archive and committed ledger checkpoint as the recovery boundary. Workers may restart, databases may be rebuilt, and serving projections may be replaced, but the system must never skip history or serve a projection whose coverage no longer matches its evidence store.
01 / Invariants
Conditions that stop the pipeline.
- the database is permanently bound to one Stellar network ID;
- committed ledgers form one contiguous range and agree on the hash chain;
- parallel decoders may finish out of order, but commits remain in ledger order;
- a failed decode or write cannot advance the committed checkpoint;
- failed transactions never mutate materialized current state;
- historical replay never enters the live notification outbox;
- an unrecognized parser or schema version fails visibly instead of being guessed;
- the read API rejects a serving projection with stale or incompatible coverage.
02 / Health model
Expose progress at every boundary.
| Signal | Why it matters | Status |
|---|---|---|
| Archive partition freshness and completion | Shows whether the local recovery surface is current and complete. | Partially implemented in markers and logs |
| Indexed ledger start/end and contract transaction count | States the exact bounded coverage served by the demo. | Implemented in /health |
| Last fetched, decoded, and committed ledger | Separates source lag, parser lag, and database lag. | Planned for live ingestion |
| Parser failures by module and version | Prevents silent coverage loss after a protocol upgrade. | Planned |
| Serving generation and coverage match | Stops stale rankings when the compact range advances. | Implemented |
| Outbox age, retries, and channel delivery status | Separates detection success from notification success. | Planned |
03 / Failure modes
Expected response by failure class.
Remote source unavailable
Keep the committed checkpoint, retry with bounded backoff, then select the documented fallback source.
Archive ledger missing
Stop before opening a commit that would create a sparse range. Resynchronize that partition and retry.
Hash conflict
Stop ingestion and raise an operator incident. Do not resolve conflicting history automatically.
Unsupported XDR or Wasm
Preserve the raw record and coverage failure; generic facts may continue only when the ledger itself remains safely decodable.
Serving snapshot stale
Keep exact compact relationships available, return rankings as unavailable, rebuild, validate, and atomically publish.
Delivery channel unavailable
Retain the committed outbox event, retry idempotently, and report channel failure without rolling back chain facts.
04 / Publication
Build beside production, then rename.
- Open historical evidence read-only. The finalizer cannot modify the compact database.
- Write a new generation. Progress checkpoints and shard files make a long aggregation resumable.
- Create query indexes last. Bulk aggregation stays sequential and avoids maintaining rankings row by row.
- Validate schema and coverage. Required metadata and exact index key ordering are part of the read contract.
- Atomically replace the active file. The read API detects the new generation on the next request without restarting.
05 / Backup priority
Back up what cannot be regenerated first.
| Asset | Regenerable? | Priority |
|---|---|---|
| Protocol registry sources, parser versions, and configuration | No—not without reconstructing research decisions | Highest |
| Alert-control policy and future delivery state | No | Highest |
| Local raw archive | Usually, while the upstream object remains available | High due to recovery time and bandwidth |
| Compact evidence database | Yes, from raw archive plus exact code/config version | Medium |
| Serving snapshot | Yes, from the compact database | Low |