Aegis Architecture — Four Defense Layers

How it works:

1. Before any schema change is applied to your database, Aegis inspects the generated change set for anything destructive — dropped tables, dropped columns, or truncates.
2. For each affected table, Aegis counts the live rows that would be lost.
3. If any non-empty table would be affected:

The guard never auto-overrides itself — a destructive change always requires an explicit, logged decision before it can proceed, and the automatic snapshot means an override is always undoable.

Architecture. PITR runs on a pluggable backend — the production path wraps pgBackRest directly, an external option targets customer-managed Postgres + pgBackRest, and there's an honest fallback for when PITR isn't configured at all (it reports itself as unavailable rather than pretending to protect you).

pgBackRest configuration (generated by Aegis for you):

``` [global] repo1-type=s3 repo1-s3-endpoint=s3.us-east-1.amazonaws.com repo1-s3-bucket=your-aegis-bucket repo1-s3-region=us-east-1 repo1-cipher-type=aes-256-cbc repo1-cipher-pass=<securely generated and stored> compress-type=zst compress-level=3 archive-async=y archive-push-queue-max=4GiB

[aeion] pg1-path=/var/lib/postgresql/16/main ```

`postgresql.conf` edits (applied automatically):

wal_level = replica archive_mode = on archive_command = 'pgbackrest --stanza=aeion archive-push %p' archive_timeout = 60 # forces a switch every 60s under low write load

Schedule. Base backups run every 6 hours by default; status refreshes every 5 minutes.

Events emitted:

• aegis.pitr.base_backup_completed
• aegis.pitr.base_backup_failed
• aegis.pitr.status_refreshed
• aegis.pitr.archive_lag_high (when WAL lag exceeds threshold)
• aegis.pitr.recovery_window_shrunk (when retention rolls forward)

Status endpoint response (GET /api/v1/platform/aegis/pitr/status):

json { "configured": true, "streaming": true, "lastBaseBackupAt": "2026-05-30T06:00:00Z", "lastBaseBackupSizeBytes": 52428800000, "archiveLagSeconds": 12, "archiveFailureCount24h": 0, "recoveryWindowStart": "2026-05-01T00:00:00Z", "recoveryWindowEnd": "2026-05-31T09:12:00Z", "lastVerificationAt": "2026-05-29T03:00:00Z", "lastVerificationResult": "passed", "nextScheduledBaseBackupAt": "2026-05-31T12:00:00Z" }

Architecture. The restore engine pairs with the backup pipeline — backups produce snapshots, and the restore engine consumes them for full-DB, schema, table, or single-collection restores.

Backup pipeline. Aegis runs a standard pg_dump, compresses it, and streams it directly to your S3-compatible bucket. Each snapshot job moves through a simple state machine:

pending → running → completed ↓ failed

Restore modes:

• full — drop+recreate the database (an automatic rollback snapshot is taken first)
• schema — restore a single schema
• tables — restore one or more specific tables
• collection — extract one collection's table + its associated indexes
• pitr_in_place — Layer 2 path, restoring point-in-time directly against the live data directory
• pitr_sidecar — Layer 2 path, restoring into a temporary, isolated Postgres instance instead

Restore job states:

pending → running → completed ↓ failed → rolled_back (auto-rollback via the pre-restore snapshot)

Pre-restore preview — before applying a restore, Aegis previews exactly what will change (which tables, how much data) without touching your live data. This powers the "what will change?" step in the restore wizard.

S3 cleanup happens automatically — old backup job records and their corresponding S3 objects are deleted together, so orphaned files never accumulate in your bucket.

Every write to a temporal-enabled collection is intercepted automatically and recorded as a reverse patch — a compact record of exactly how to undo that change. Point-in-time document reconstruction replays those patches against the current state to produce what the document looked like at any past moment.

Each event records which document changed, who changed it, when, and the reverse patch needed to undo it — indexed for fast per-document lookup.

Reconstruction algorithm:

1. Find the latest version of the document AT OR BEFORE the target timestamp.
2. Apply reverse patches in newest-to-oldest order to produce the historical state.
3. If the document didn't exist at the target time, return null.

QueryBuilder API:

typescript const post = await ctx.services["posts"] .query(ctx) .where({ id: "post_abc" }) .asOf("2026-05-15T10:30:00Z") .first();

A matching per-document HTTP route factory (reconstruct / history / timeline / compare) ships in @aeion/core, ready for any module to mount — the QueryBuilder .asOf() API above is the primary, currently-wired way tenants and modules reach this capability today.

Bulk Undo — filter by user / time / collection, reverse in one call:

POST /api/v1/platform/aegis/bulk-undo/execute { "tenantId": "t1", "filter": { "userId": "agent_x", "timeRange": { "from": "2026-05-18T09:00:00Z", "to": "2026-05-18T09:15:00Z" }, "collections": ["contacts", "deals"] } } // → { "reverted": 87, "errors": [], "elapsedMs": 2483 }

The same filter can be sent to POST /api/v1/platform/aegis/bulk-undo/preview first to see what would be reverted without applying anything.

Bulk Undo coordinates cross-collection consistency — if reverting a delete on deals requires recreating a deleted contacts row, reversals are ordered correctly.

Retention — historical event data is purged automatically beyond your configured retention window. Defaults to 365 days; tunable per collection.

Aegis maintains a full operational record of everything it does, so nothing about your backup and recovery posture is a black box:

• Storage configuration — your BYOB provider settings, with credentials encrypted at rest
• Backup + restore history — every snapshot and restore job, its status, and rollback tracking so any restore can be undone
• Verification results — every weekly verification run, pass/fail, and measured RTO
• Compliance report archive — every generated monthly report
• PITR setup + status — bootstrap progress and live pipeline health
• Encryption key audit trail — key generation, rotation, and import events (metadata only — the plaintext key itself is never stored)
• Version history retention audit — what was purged under Layer 4 retention, when, and why
• GDPR erasure audit log — a full record of right-to-erasure purges