---
title: "Philosophy"
description: "Why Peregrine is built the way it is — format fidelity, no runtime Python, sealed deploys, and the Python oracle."
---

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

# Philosophy

Peregrine makes a few deliberate bets. They explain why it looks the way it does
and where its guarantees come from.

## Format fidelity over everything

Reproducing an accepted Swift format exactly can enable mixed-version
interoperation and node-by-node rollout. Therefore each implemented serialized
format — the ring, SQLite databases, diskfile layout, pickled hashes, crypto
metadata, HMAC signatures, and EC fragment archives — is treated as a
compatibility contract, not an implementation detail. Compatibility is claimed
only where the matching oracle evidence exists.

## The oracle is Python, not ourselves

Correctness claims are checked against the real Python implementation, not
against Peregrine's own expectations. Golden fixtures are generated by running
the actual Python code; the Rust is verified to produce byte-identical output,
in both directions. A test that only checks what the Rust happens to do proves
nothing.

## No runtime Python

Every component is a self-contained Rust binary. The Python tree is not vendored
into this repo — it lives upstream and is used only to generate the golden
fixtures. The deployer, in particular, runs the upstream Ansible plan **without**
Ansible or Python at runtime.

## Sealed, reversible operations

Cluster-changing tools are designed around bounded, reviewable, reversible
actions:

1. **Step 1**

   **Deploys are sealed.** A plan is hashed before it is applied and re-verified
   against that hash; a plan that changed after sealing does not apply. Destructive
   capabilities (disk wipe, firewall, SSH reconfig) each require separate
   authorization.
2. **Step 2**

   **Guarded Lab mutations are journaled.** Supported fault actions record an
   undo before acting and use a TTL sweeper. Operators still verify recovery; a
   journal is not proof that every external failure healed.

## Honest instrumentation

A diagnostic that scores a failed probe as "fine" is worse than no diagnostic.
Health tooling prints `UNKNOWN` for anything it cannot determine, and reports
state what was actually observed — including failures and skips — rather than
what the result happens to be.

## Streaming, bounded memory

The candidate object path is designed to stream through bounded buffers rather
than materialize object-sized bodies. G3 proves that each route actually uses
the native path; G7 measures buffer/RSS bounds under large bodies, slow clients,
cancellation, and overload. Bounded memory is a correctness gate, not an
architectural slogan.

Source: https://docs.myswift.rs/philosophy/index.mdx