sovereign-sdk-edge 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- sovereign_sdk_edge-0.1.0/PKG-INFO +132 -0
- sovereign_sdk_edge-0.1.0/README.md +112 -0
- sovereign_sdk_edge-0.1.0/pyproject.toml +35 -0
- sovereign_sdk_edge-0.1.0/setup.cfg +4 -0
- sovereign_sdk_edge-0.1.0/src/sovereign_edge/__init__.py +30 -0
- sovereign_sdk_edge-0.1.0/src/sovereign_edge/buffer.py +1157 -0
- sovereign_sdk_edge-0.1.0/src/sovereign_edge/models.py +177 -0
- sovereign_sdk_edge-0.1.0/src/sovereign_edge/pipeline.py +655 -0
- sovereign_sdk_edge-0.1.0/src/sovereign_sdk_edge.egg-info/PKG-INFO +132 -0
- sovereign_sdk_edge-0.1.0/src/sovereign_sdk_edge.egg-info/SOURCES.txt +12 -0
- sovereign_sdk_edge-0.1.0/src/sovereign_sdk_edge.egg-info/dependency_links.txt +1 -0
- sovereign_sdk_edge-0.1.0/src/sovereign_sdk_edge.egg-info/requires.txt +6 -0
- sovereign_sdk_edge-0.1.0/src/sovereign_sdk_edge.egg-info/top_level.txt +1 -0
- sovereign_sdk_edge-0.1.0/tests/test_edge.py +3654 -0
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: sovereign-sdk-edge
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Middleware pipeline bridging sovereign-sensor raw intake and sovereign-ledger immutable storage via sovereign-sieve payload transformation
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
Project-URL: Homepage, https://github.com/kenwalger/sovereign-sdk
|
|
7
|
+
Project-URL: Repository, https://github.com/kenwalger/sovereign-sdk
|
|
8
|
+
Project-URL: Changelog, https://github.com/kenwalger/sovereign-sdk/blob/main/CHANGELOG.md
|
|
9
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
10
|
+
Classifier: Intended Audience :: Developers
|
|
11
|
+
Classifier: Topic :: Security
|
|
12
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
13
|
+
Requires-Python: >=3.12
|
|
14
|
+
Description-Content-Type: text/markdown
|
|
15
|
+
Requires-Dist: sovereign-core>=1.1.0
|
|
16
|
+
Requires-Dist: sovereign-ledger>=1.1.0
|
|
17
|
+
Requires-Dist: sovereign-sieve>=1.1.0
|
|
18
|
+
Provides-Extra: dev
|
|
19
|
+
Requires-Dist: sovereign-sensor>=0.1.0; extra == "dev"
|
|
20
|
+
|
|
21
|
+
# sovereign-edge
|
|
22
|
+
|
|
23
|
+
**High-Integrity Middleware Pipeline and Asynchronous Ingestion Bridge for Sovereign Systems.**
|
|
24
|
+
|
|
25
|
+
`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`.
|
|
26
|
+
|
|
27
|
+
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.
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## Architecture Overview
|
|
32
|
+
|
|
33
|
+
The pipeline operates as a deterministic, four-stage loop running with zero network dependencies:
|
|
34
|
+
|
|
35
|
+
```mermaid
|
|
36
|
+
graph TD
|
|
37
|
+
A[Raw Wire Bytes] -->|1. Deserialize| B(SensorFrame)
|
|
38
|
+
B -->|2. Sieve Pass| C{Prose Tax Optimization}
|
|
39
|
+
C -->|Success| D[Refined Bytes]
|
|
40
|
+
C -->|Sieve Fault| E[Raw Passthrough / sieve_fault=True]
|
|
41
|
+
D -->|3. Sign Phase| F(Ed25519 ForensicReceipt)
|
|
42
|
+
E -->|3. Sign Phase| F
|
|
43
|
+
F -->|4. Dispatch Target| G{SovereignLedger}
|
|
44
|
+
G -->|Storage Error / Offline| H[OffGridBuffer]
|
|
45
|
+
H -->|Async Thread + fsync| I[JSONL Disk Log]
|
|
46
|
+
I -->|Chronological drain()| G
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
1. **Deserialize:** Extracts the seven-key minified wire frame (`v`, `n`, `t`, `q`, `alg`, `d`, `s`) arriving from embedded hardware via `SensorFrame.from_bytes()`.
|
|
50
|
+
2. **Sieve:** Executes a local token-reduction pass via `sieve_with_metrics()` to strip conversational padding and whitespace anomalies.
|
|
51
|
+
3. **Sign:** Mints a local `ForensicReceipt` via `SovereignKeyManager`, sealing both the payload hash and the transformation telemetry with an Ed25519 identity.
|
|
52
|
+
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.
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## Core Implementations
|
|
57
|
+
|
|
58
|
+
### Inbound Intake Contract: `SensorFrame`
|
|
59
|
+
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.
|
|
60
|
+
|
|
61
|
+
### Asynchronous Durability: `OffGridBuffer`
|
|
62
|
+
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.
|
|
63
|
+
|
|
64
|
+
* **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.
|
|
65
|
+
* **Atomic Clears:** To eliminate dual-replay windows during crashes, the queue clears itself using an atomic `tempfile` promotion loop.
|
|
66
|
+
|
|
67
|
+
### Resilient Processing: `EdgePipeline`
|
|
68
|
+
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.
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
## Installation & Workspace Configuration
|
|
73
|
+
|
|
74
|
+
Register the package inside your local environment or workspace architecture using Python packaging tools:
|
|
75
|
+
|
|
76
|
+
```toml
|
|
77
|
+
[project]
|
|
78
|
+
name = "sovereign-edge"
|
|
79
|
+
version = "0.1.0"
|
|
80
|
+
dependencies = [
|
|
81
|
+
"sovereign-core>=1.1.0",
|
|
82
|
+
"sovereign-ledger>=1.1.0",
|
|
83
|
+
"sovereign-sieve>=1.1.0",
|
|
84
|
+
]
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
---
|
|
88
|
+
|
|
89
|
+
## Quick Start Usage
|
|
90
|
+
|
|
91
|
+
```python
|
|
92
|
+
from sovereign_edge import EdgePipeline
|
|
93
|
+
from sovereign_ledger import SovereignLedger
|
|
94
|
+
|
|
95
|
+
# Initialize destination tier
|
|
96
|
+
ledger = SovereignLedger(".keys/sovereign_audit.db")
|
|
97
|
+
|
|
98
|
+
# Bind middleware pipeline.
|
|
99
|
+
# sensor_secret is mandatory by default; pass allow_unauthenticated=True only
|
|
100
|
+
# when operating in an environment where HMAC-SHA256 frame verification is
|
|
101
|
+
# explicitly not required.
|
|
102
|
+
pipeline = EdgePipeline(
|
|
103
|
+
ledger=ledger,
|
|
104
|
+
signing_key=".keys/edge_identity.pem",
|
|
105
|
+
buffer_path=".edge_buffer.jsonl",
|
|
106
|
+
sensor_secret=b"<shared-hmac-secret>",
|
|
107
|
+
)
|
|
108
|
+
|
|
109
|
+
# Process incoming wire frames arriving from sovereign-sensor hardware
|
|
110
|
+
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}'
|
|
111
|
+
result = pipeline.process(raw_sensor_bytes)
|
|
112
|
+
|
|
113
|
+
print(f"Committed Hash: {result.payload_hash}")
|
|
114
|
+
print(f"Buffered Status: {result.buffered}") # True if ledger was locked/offline
|
|
115
|
+
|
|
116
|
+
# Recovery Pass: When ledger locks release, flush the off-grid queue chronologically
|
|
117
|
+
if pipeline.buffer_depth > 0:
|
|
118
|
+
committed_hashes = pipeline.drain_buffer()
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
---
|
|
122
|
+
|
|
123
|
+
## Operational Verification Properties
|
|
124
|
+
|
|
125
|
+
Every engineering iteration is validated using a comprehensive desktop test harness ensuring the following pipeline invariants remain unbroken:
|
|
126
|
+
|
|
127
|
+
| Invariant Verification Property | Target File | Verification Metric |
|
|
128
|
+
| :--- | :--- | :--- |
|
|
129
|
+
| **Zero-Block Ingestion** | `buffer.py` | Asynchronous worker protects ingestion loops from blocking system execution. |
|
|
130
|
+
| **Sequence Continuity** | `buffer.py` | Playback logic enforces strict ascending sort order by source counter values. |
|
|
131
|
+
| **Fault Containment** | `pipeline.py` | Sieve-layer runtime anomalies degrade to a raw passthrough marked with explicit fault tags. |
|
|
132
|
+
| **Hash-Chain Stability** | `tests/` | Post-drain replay states leave destination ledger linearity intact. |
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
# sovereign-edge
|
|
2
|
+
|
|
3
|
+
**High-Integrity Middleware Pipeline and Asynchronous Ingestion Bridge for Sovereign Systems.**
|
|
4
|
+
|
|
5
|
+
`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`.
|
|
6
|
+
|
|
7
|
+
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.
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## Architecture Overview
|
|
12
|
+
|
|
13
|
+
The pipeline operates as a deterministic, four-stage loop running with zero network dependencies:
|
|
14
|
+
|
|
15
|
+
```mermaid
|
|
16
|
+
graph TD
|
|
17
|
+
A[Raw Wire Bytes] -->|1. Deserialize| B(SensorFrame)
|
|
18
|
+
B -->|2. Sieve Pass| C{Prose Tax Optimization}
|
|
19
|
+
C -->|Success| D[Refined Bytes]
|
|
20
|
+
C -->|Sieve Fault| E[Raw Passthrough / sieve_fault=True]
|
|
21
|
+
D -->|3. Sign Phase| F(Ed25519 ForensicReceipt)
|
|
22
|
+
E -->|3. Sign Phase| F
|
|
23
|
+
F -->|4. Dispatch Target| G{SovereignLedger}
|
|
24
|
+
G -->|Storage Error / Offline| H[OffGridBuffer]
|
|
25
|
+
H -->|Async Thread + fsync| I[JSONL Disk Log]
|
|
26
|
+
I -->|Chronological drain()| G
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
1. **Deserialize:** Extracts the seven-key minified wire frame (`v`, `n`, `t`, `q`, `alg`, `d`, `s`) arriving from embedded hardware via `SensorFrame.from_bytes()`.
|
|
30
|
+
2. **Sieve:** Executes a local token-reduction pass via `sieve_with_metrics()` to strip conversational padding and whitespace anomalies.
|
|
31
|
+
3. **Sign:** Mints a local `ForensicReceipt` via `SovereignKeyManager`, sealing both the payload hash and the transformation telemetry with an Ed25519 identity.
|
|
32
|
+
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.
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## Core Implementations
|
|
37
|
+
|
|
38
|
+
### Inbound Intake Contract: `SensorFrame`
|
|
39
|
+
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.
|
|
40
|
+
|
|
41
|
+
### Asynchronous Durability: `OffGridBuffer`
|
|
42
|
+
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.
|
|
43
|
+
|
|
44
|
+
* **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.
|
|
45
|
+
* **Atomic Clears:** To eliminate dual-replay windows during crashes, the queue clears itself using an atomic `tempfile` promotion loop.
|
|
46
|
+
|
|
47
|
+
### Resilient Processing: `EdgePipeline`
|
|
48
|
+
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.
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## Installation & Workspace Configuration
|
|
53
|
+
|
|
54
|
+
Register the package inside your local environment or workspace architecture using Python packaging tools:
|
|
55
|
+
|
|
56
|
+
```toml
|
|
57
|
+
[project]
|
|
58
|
+
name = "sovereign-edge"
|
|
59
|
+
version = "0.1.0"
|
|
60
|
+
dependencies = [
|
|
61
|
+
"sovereign-core>=1.1.0",
|
|
62
|
+
"sovereign-ledger>=1.1.0",
|
|
63
|
+
"sovereign-sieve>=1.1.0",
|
|
64
|
+
]
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
---
|
|
68
|
+
|
|
69
|
+
## Quick Start Usage
|
|
70
|
+
|
|
71
|
+
```python
|
|
72
|
+
from sovereign_edge import EdgePipeline
|
|
73
|
+
from sovereign_ledger import SovereignLedger
|
|
74
|
+
|
|
75
|
+
# Initialize destination tier
|
|
76
|
+
ledger = SovereignLedger(".keys/sovereign_audit.db")
|
|
77
|
+
|
|
78
|
+
# Bind middleware pipeline.
|
|
79
|
+
# sensor_secret is mandatory by default; pass allow_unauthenticated=True only
|
|
80
|
+
# when operating in an environment where HMAC-SHA256 frame verification is
|
|
81
|
+
# explicitly not required.
|
|
82
|
+
pipeline = EdgePipeline(
|
|
83
|
+
ledger=ledger,
|
|
84
|
+
signing_key=".keys/edge_identity.pem",
|
|
85
|
+
buffer_path=".edge_buffer.jsonl",
|
|
86
|
+
sensor_secret=b"<shared-hmac-secret>",
|
|
87
|
+
)
|
|
88
|
+
|
|
89
|
+
# Process incoming wire frames arriving from sovereign-sensor hardware
|
|
90
|
+
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}'
|
|
91
|
+
result = pipeline.process(raw_sensor_bytes)
|
|
92
|
+
|
|
93
|
+
print(f"Committed Hash: {result.payload_hash}")
|
|
94
|
+
print(f"Buffered Status: {result.buffered}") # True if ledger was locked/offline
|
|
95
|
+
|
|
96
|
+
# Recovery Pass: When ledger locks release, flush the off-grid queue chronologically
|
|
97
|
+
if pipeline.buffer_depth > 0:
|
|
98
|
+
committed_hashes = pipeline.drain_buffer()
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
---
|
|
102
|
+
|
|
103
|
+
## Operational Verification Properties
|
|
104
|
+
|
|
105
|
+
Every engineering iteration is validated using a comprehensive desktop test harness ensuring the following pipeline invariants remain unbroken:
|
|
106
|
+
|
|
107
|
+
| Invariant Verification Property | Target File | Verification Metric |
|
|
108
|
+
| :--- | :--- | :--- |
|
|
109
|
+
| **Zero-Block Ingestion** | `buffer.py` | Asynchronous worker protects ingestion loops from blocking system execution. |
|
|
110
|
+
| **Sequence Continuity** | `buffer.py` | Playback logic enforces strict ascending sort order by source counter values. |
|
|
111
|
+
| **Fault Containment** | `pipeline.py` | Sieve-layer runtime anomalies degrade to a raw passthrough marked with explicit fault tags. |
|
|
112
|
+
| **Hash-Chain Stability** | `tests/` | Post-drain replay states leave destination ledger linearity intact. |
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77.0.0"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "sovereign-sdk-edge"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Middleware pipeline bridging sovereign-sensor raw intake and sovereign-ledger immutable storage via sovereign-sieve payload transformation"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.12"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
dependencies = [
|
|
13
|
+
"sovereign-core>=1.1.0",
|
|
14
|
+
"sovereign-ledger>=1.1.0",
|
|
15
|
+
"sovereign-sieve>=1.1.0",
|
|
16
|
+
]
|
|
17
|
+
classifiers = [
|
|
18
|
+
"Programming Language :: Python :: 3.12",
|
|
19
|
+
"Intended Audience :: Developers",
|
|
20
|
+
"Topic :: Security",
|
|
21
|
+
"Topic :: Software Development :: Libraries",
|
|
22
|
+
]
|
|
23
|
+
|
|
24
|
+
[project.urls]
|
|
25
|
+
Homepage = "https://github.com/kenwalger/sovereign-sdk"
|
|
26
|
+
Repository = "https://github.com/kenwalger/sovereign-sdk"
|
|
27
|
+
Changelog = "https://github.com/kenwalger/sovereign-sdk/blob/main/CHANGELOG.md"
|
|
28
|
+
|
|
29
|
+
[project.optional-dependencies]
|
|
30
|
+
dev = [
|
|
31
|
+
"sovereign-sensor>=0.1.0",
|
|
32
|
+
]
|
|
33
|
+
|
|
34
|
+
[tool.setuptools.packages.find]
|
|
35
|
+
where = ["src"]
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# packages/sovereign-edge/src/sovereign_edge/__init__.py
|
|
2
|
+
"""sovereign-edge — Middleware pipeline bridging sovereign-sensor raw intake and sovereign-ledger immutable storage.
|
|
3
|
+
|
|
4
|
+
Intercepts sealed sensor envelopes from sovereign-sensor, applies the sovereign-sieve
|
|
5
|
+
Prose Tax transformation to produce a verified, minimized payload, and dispatches a
|
|
6
|
+
signed ForensicReceipt to sovereign-ledger. An off-grid JSONL buffer absorbs receipts
|
|
7
|
+
when the ledger is temporarily unreachable. Zero network dependencies; all operations
|
|
8
|
+
are strictly local-first.
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from .buffer import OffGridBuffer
|
|
12
|
+
from .models import EdgeResult, SensorFrame
|
|
13
|
+
from .pipeline import (
|
|
14
|
+
EdgePipeline,
|
|
15
|
+
SovereignConfigurationError,
|
|
16
|
+
SovereignDoubleFaultError,
|
|
17
|
+
SovereignRequeueAllocationError,
|
|
18
|
+
)
|
|
19
|
+
|
|
20
|
+
__version__ = "0.1.0"
|
|
21
|
+
|
|
22
|
+
__all__ = [
|
|
23
|
+
"EdgePipeline",
|
|
24
|
+
"EdgeResult",
|
|
25
|
+
"OffGridBuffer",
|
|
26
|
+
"SensorFrame",
|
|
27
|
+
"SovereignConfigurationError",
|
|
28
|
+
"SovereignDoubleFaultError",
|
|
29
|
+
"SovereignRequeueAllocationError",
|
|
30
|
+
]
|