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.
@@ -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,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -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
+ ]