Skip to main content

sovereign-edge

High-Integrity Middleware Pipeline and Asynchronous Ingestion Bridge for Sovereign Systems.

sovereign-edge acts as the durable middle-tier intake handler for the Sovereign Systems ecosystem. It intercepts sealed sensor wire envelopes generated at the point of data genesis by sovereign-sensor, processes them locally using sovereign-sieve to enforce Prose Tax token optimization, and commits the resulting high-integrity records to sovereign-ledger.

To insulate the runtime environment from disk I/O bottlenecks and network volatility, sovereign-edge features an off-grid background journaling buffer that preserves strict chronological ordering and fault-mode custody loops.


Architecture Overview

The pipeline operates as a deterministic, four-stage loop running with zero network dependencies:

graph TD
    A[Raw Wire Bytes] -->|1. Deserialize| B(SensorFrame)
    B -->|2. Sieve Pass| C{Prose Tax Optimization}
    C -->|Success| D[Refined Bytes]
    C -->|Sieve Fault| E[Raw Passthrough / sieve_fault=True]
    D -->|3. Sign Phase| F(Ed25519 ForensicReceipt)
    E -->|3. Sign Phase| F
    F -->|4. Dispatch Target| G{SovereignLedger}
    G -->|Storage Error / Offline| H[OffGridBuffer]
    H -->|Async Thread + fsync| I[JSONL Disk Log]
    I -->|Chronological drain()| G
  1. Deserialize: Extracts the seven-key minified wire frame (v, n, t, q, alg, d, s) arriving from embedded hardware via SensorFrame.from_bytes().
  2. Sieve: Executes a local token-reduction pass via sieve_with_metrics() to strip conversational padding and whitespace anomalies.
  3. Sign: Mints a local ForensicReceipt via SovereignKeyManager, sealing both the payload hash and the transformation telemetry with an Ed25519 identity.
  4. Commit: Attempts to write immediately to the ledger, falling back seamlessly to an isolated daemon background thread that manages durable disk-bound serialization if the target is locked or offline.

Core Implementations

Inbound Intake Contract: SensorFrame

The pipeline maps incoming wire bytes directly to a typed SensorFrame dataclass. To guarantee that validation metrics are independent of dictionary key insertion order, text_content() exposes a deterministic, sort-keyed, ensure_ascii=False serialization surface for downstream ingestion.

Asynchronous Durability: OffGridBuffer

When log destinations are unreachable, entries pass into a single-line JSONL-backed file queue. Writes are dispatched to an isolated daemon background thread, decoupling caller execution from blocking disk-bound os.fsync latency.

  • Chronological Ordering: Every entry carries an internal hardware sequence identifier (q). During a ledger recovery pass, drain() flushes background I/O handles and sorts the file records by ascending sequence before replay, protecting the linearity of the destination hash chain.
  • Atomic Clears: To eliminate dual-replay windows during crashes, the queue clears itself using an atomic tempfile promotion loop.

Resilient Processing: EdgePipeline

The EdgePipeline coordinates execution through strict exception isolation barriers. If sovereign-sieve encounters an anomalous payload structure, processing falls back seamlessly to the raw text payload, sets tax metrics to 0.0, and stamps sieve_fault=True inside the ledger metadata. The audit record is never broken.


Installation & Workspace Configuration

Register the package inside your local environment or workspace architecture using Python packaging tools:

[project]
name = "sovereign-sdk-edge"
version = "1.3.0"
dependencies = [
    "sovereign-sdk-core>=1.3.0",
    "sovereign-sdk-ledger>=1.3.0",
    "sovereign-sdk-sieve>=1.3.0",
]

Quick Start Usage

from sovereign_edge import EdgePipeline
from sovereign_ledger import SovereignLedger

# Initialize destination tier
ledger = SovereignLedger(".keys/sovereign_audit.db")

# Bind middleware pipeline.
# sensor_secret is mandatory by default; pass allow_unauthenticated=True only
# when operating in an environment where HMAC-SHA256 frame verification is
# explicitly not required.
pipeline = EdgePipeline(
    ledger=ledger,
    signing_key=".keys/edge_identity.pem",
    buffer_path=".edge_buffer.jsonl",
    sensor_secret=b"<shared-hmac-secret>",
)

# Process incoming wire frames arriving from sovereign-sensor hardware
raw_sensor_bytes = b'{"alg":"hmac-sha256","d":{"temp":23.4},"n":"node-01","q":42,"s":"...","t":"2026-06-19T10:00:00Z","v":1}'
result = pipeline.process(raw_sensor_bytes)

print(f"Committed Hash: {result.payload_hash}")
print(f"Buffered Status: {result.buffered}")  # True if ledger was locked/offline

# Recovery Pass: When ledger locks release, flush the off-grid queue chronologically
if pipeline.buffer_depth > 0:
    committed_hashes = pipeline.drain_buffer()

Replay deduplication and ledger upgrades

Each receipt is appended with its signature as the ledger idempotency key. A receipt replayed from the off-grid buffer after a crash repeats that key and is dropped instead of being recorded twice. Two receipts minted from identical sensor content at different times carry distinct signatures and are both recorded. Ed25519 signing is deterministic, so processing the same frame twice within one clock tick mints a byte-identical receipt with the same signature, and the second is treated as a replay.

Before upgrading sovereign-sdk-ledger past 1.3.0, drain the off-grid buffer (pipeline.drain_buffer()) before the first open on the new release. That open migrates the ledger file, and receipts committed before the migration carry no idempotency key. A buffered receipt that was already committed before migration would therefore be recorded a second time. The migration does not backfill keys for existing entries.


Operational Verification Properties

Every engineering iteration is validated using a comprehensive desktop test harness ensuring the following pipeline invariants remain unbroken:

Invariant Verification Property Target File Verification Metric
Zero-Block Ingestion buffer.py Asynchronous worker protects ingestion loops from blocking system execution.
Sequence Continuity buffer.py Playback logic enforces strict ascending sort order by source counter values.
Fault Containment pipeline.py Sieve-layer runtime anomalies degrade to a raw passthrough marked with explicit fault tags.
Hash-Chain Stability tests/ Post-drain replay states leave destination ledger linearity intact.

Metadata

Release files for sovereign-sdk-edge 1.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sovereign-sdk-edge 1.5.0
File Size Uploaded Provenance Actions
sovereign_sdk_edge-1.5.0.tar.gz 65.7 kB With provenance Details for sovereign_sdk_edge-1.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for sovereign-sdk-edge 1.5.0
File Interpreter ABI Platform Actions
sovereign_sdk_edge-1.5.0-py3-none-any.whl Python 3 none any Details for sovereign_sdk_edge-1.5.0-py3-none-any.whl

Total release size: 99.7 kB

Release files / sovereign_sdk_edge-1.5.0.tar.gz

Download URL sovereign_sdk_edge-1.5.0.tar.gz
Size 65.7 kB
Tags Source
SHA-256 checksum
How to use checksums
8822d21b3aba4f497ca21690c8731e3ea3fbd04d06f226c66e0b9aafa065e8e3
BLAKE2b-256 checksum
How to use checksums
224554700e0987f26c621625d75cc8a1a1be522fa7c68c04eb26e4ab1aa31daf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

Release files / sovereign_sdk_edge-1.5.0-py3-none-any.whl

Download URL sovereign_sdk_edge-1.5.0-py3-none-any.whl
Size 34.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2cc0b3869e3c91bb2da7b72212fcec0b98b2de1480b0485b96d41ca246383817
BLAKE2b-256 checksum
How to use checksums
f7da74d1050f1aa0749e500c0e2cee86d37d52840e20cb06fa820539e8d96214
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

Security for sovereign-sdk-edge 1.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for sovereign_sdk_edge-1.5.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.5.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page