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
- Deserialize: Extracts the seven-key minified wire frame (
v,n,t,q,alg,d,s) arriving from embedded hardware viaSensorFrame.from_bytes(). - Sieve: Executes a local token-reduction pass via
sieve_with_metrics()to strip conversational padding and whitespace anomalies. - Sign: Mints a local
ForensicReceiptviaSovereignKeyManager, sealing both the payload hash and the transformation telemetry with an Ed25519 identity. - 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
tempfilepromotion 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.