release: publish Sofia Engine 3.0.0a1 artifacts, manifests, and documentation

LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

NOTICE

@@ -0,0 +1,30 @@
+Sofia Engine
+Copyright 2026 Rootcastle Engineering & Innovation
+Project home: https://github.com/rootcastleco/sofia-ai
+
+This product includes software developed by the Rootcastle Engineering &
+Innovation team.
+
+========================================================================
+Third-party notices
+========================================================================
+
+Sofia Engine depends at runtime on NumPy, and optionally on third-party
+packages for integrations (MQTT, Modbus, serial, ONNX Runtime, PyTorch,
+FastAPI/uvicorn, and the MkDocs documentation toolchain). Their respective
+license and copyright notices apply:
+
+- NumPy — BSD 3-Clause
+- paho-mqtt / pymodbus / pyserial — their respective licenses
+- ONNX Runtime — MIT
+- PyTorch — BSD 3-Clause
+- FastAPI / uvicorn — MIT
+- MkDocs — BSD 2-Clause
+
+The embedded C reference implementation (embedded/) is original work and is
+released under the same Apache-2.0 license as the rest of the project.
+
+The test suite makes use of pytest, pytest-cov, Hypothesis, ruff and mypy,
+which are licensed under their respective permissive licenses.
+
+No vendored copies of third-party source code are shipped in this repository.

README.md

@@ -1,3 +1,203 @@
 ---
 license: apache-2.0
+doi: 10.57967/hf/10549
+language:
+  - en
+tags:
+  - edge-ai
+  - industrial-ai
+  - scientific-computing
+  - embedded-ai
+  - signal-processing
+  - digital-signal-processing
+  - predictive-maintenance
+  - condition-monitoring
+  - vibration-analysis
+  - anomaly-detection
+  - industrial-iot
+  - iiot
+  - telemetry
+  - edge-computing
+  - tinyml
+  - on-device-learning
+  - embedded-systems
+  - machine-health
+  - time-series
+  - python
+  - typescript
+  - c
+library_name: sofia-engine
 ---
+
+# Sofia Engine — Scientific & Edge Intelligence Runtime
+
+Developed by **Rootcastle Engineering & Innovation**  
+Canonical Source Repository: [github.com/rootcastleco/sofia-ai](https://github.com/rootcastleco/sofia-ai)  
+Project Homepage: [rootcastle.com](https://rootcastle.com/)  
+DOI: [10.57967/hf/10549](https://doi.org/10.57967/hf/10549)
+
+---
+
+## 1. Overview
+
+**Sofia Engine** is an open-source scientific and edge intelligence runtime developed by Rootcastle Engineering & Innovation for deterministic physical telemetry processing, industrial signal analysis, machine-health diagnostics, bounded edge inference, and safety-gated technical automation.
+
+Operating under the engineering principle **"Evidence beats claims"**, Sofia Engine combines:
+- **Scientific DSP**: FFT, Welch PSD, Hilbert analytic amplitude envelope, and Fortescue 3-phase symmetrical components.
+- **Physical Telemetry Ingestion**: Bounded, unit-bearing telemetry frames with quality status (`GOOD`, `DEGRADED`, `SATURATED`).
+- **Versioned Feature Extraction**: 14+ statistical and spectral features packaged in ordered, reproducible `FeatureVector` contracts (Schema v3.0).
+- **Evidence-Based Diagnostics**: Noisy-OR evidence aggregation and machine health scoring with explicit uncertainty bands ($0-100 \pm \Delta$).
+- **Embedded & Edge Execution**: Hardened virtual machine (`SofiaAsmVM`), C99 zero-allocation microcontroller implementation, and experimental in-situ backpropagation.
+- **Safety & Policy Gating**: Strict default-DENY policy engine, Nonce + TTL replay protection, and an **actuation firewall that strictly isolates external LLMs from physical machinery**.
+
+> [!NOTE]
+> **Canonical Pretrained Checkpoint Status:**
+> No canonical pretrained Sofia checkpoint is distributed in this release. This repository provides the Sofia model/runtime specification, machine-readable manifests, reproducible examples, and future checkpoint distribution interfaces. When pre-trained foundation models are released, they will be published with complete training datasets, evaluation reports, and SHA-256 digests.
+
+---
+
+## 2. Subsystem Maturity Table
+
+Maturity levels are assigned strictly based on verifiable implementation and test coverage:
+
+| Subsystem | Status | Verification & Evidence |
+| :--- | :--- | :--- |
+| **Scientific DSP** | **Stable** | Parseval energy conservation verified; exact amplitude recovery to $< 10^{-14}$; 5 golden vector tests passed. |
+| **Telemetry Runtime** | **Stable** | Memory capacity ceilings ($\le 65536$), timestamp plausibility, unit alias normalization, IEEE 754 non-finite rejection. |
+| **Diagnostic Engine** | **Stable** | Deterministic Noisy-OR fusion; dynamic uncertainty intervals; quality attenuation on degraded signals. |
+| **Policy Engine & Replay Guard** | **Stable** | Default-DENY posture; Nonce + TTL monotonic replay protection; LLM actuation firewall; secret scrubbing. |
+| **Embedded C99 Runtime** | **Stable** | Zero dynamic heap allocation post-init (`malloc` prohibited); Q16.16 fixed-point arithmetic; static ceilings. |
+| **Sofia Assembly VM** | **Beta** | Memory and register bounds checking; cycle ceilings; structured execution result (`VMExecutionResult`). |
+| **In-Situ Neural Training** | **Experimental** | 2-layer analytical backpropagation in virtual assembly; validated against finite differences ($< 10^{-5}$ error). |
+| **Cross-Language Conformance** | **Beta** | Python, TypeScript SDK (`@rootcastle/sofia-engine`), and C99 verified against identical golden vectors. |
+| **LLM Copilot Integration** | **Optional** | Strictly advisory technical assistance; isolated from deterministic control core and physical actuators. |
+| **Quantum Emulation** | **Experimental** | Educational statevector simulation and VQE parameter exploration. |
+| **Native Code Generation** | **Experimental** | Preliminary x86_64 AVX2, ARM Cortex-M Thumb-2, and WebAssembly emission stubs. |
+
+---
+
+## 3. Architecture & Data Flow
+
+```mermaid
+flowchart LR
+    S["Physical Sensors"] --> I["Telemetry Ingestion"]
+    I --> Q["Validation & Signal Quality"]
+    Q --> B["Bounded Buffers"]
+    B --> D["Scientific DSP"]
+    D --> F["Versioned Feature Vector"]
+    F --> M["Inference Backends"]
+    M --> E["Evidence Fusion"]
+    E --> H["Diagnostics & Health"]
+    H --> P["Policy Engine"]
+    P --> O["Advisory / Controlled Output"]
+```
+
+**Key Architectural Invariant:** External LLMs (OpenAI, NVIDIA NIM, OpenRouter) operate exclusively as optional copilots at Layer 10. They have no read or write access to the deterministic signal processing or policy enforcement layers.
+
+---
+
+## 4. Scientific Scope & Calculations
+
+Sofia Engine implements calculations relevant to industrial engineering standards:
+
+- **Mechanical Vibration:** Implements calculations relevant to ISO 10816 / ISO 20816 vibration severity evaluation (RMS, peak, crest factor, kurtosis, skewness).
+- **Spectral Analysis:** Discrete Fourier Transform (one-sided FFT magnitude), Welch's averaged periodogram with window gain corrections, spectral centroid, spectral entropy, and spectral flatness.
+- **Envelope Demodulation:** Hilbert transform analytic signal for bearing defect and gear-mesh modulation extraction.
+- **Electrical Power Quality:** Implements calculations relevant to IEEE 519 and IEC 61000-4-30 analysis, including True RMS, Active/Reactive/Apparent Power, Total Harmonic Distortion (THD), and Fortescue 3-phase symmetrical components ($V_0, V_1, V_2, \text{VUF}$).
+- **Process Telemetry:** Thermal rates of change ($dT/dt$), pulsation peak-to-peak, and fluid pressure crest factors.
+
+*Note: Software implementation does not constitute formal laboratory certification. Operational deployment requires qualified engineering calibration.*
+
+---
+
+## 5. Installation
+
+### Core Runtime (NumPy Only)
+```bash
+pip install sofia-engine
+```
+
+### Industrial Telemetry Integrations (MQTT, Modbus, Serial)
+```bash
+pip install "sofia-engine[industrial]"
+```
+
+### From Canonical Source
+```bash
+git clone https://github.com/rootcastleco/sofia-ai.git
+cd sofia-ai
+pip install -e .
+```
+
+---
+
+## 6. Reproducible Examples
+
+Executable scripts are maintained in the [`examples/`](https://huggingface.co/rootcastleengineering/sofia/tree/main/examples) directory:
+
+- [`examples/basic_inference.py`](https://huggingface.co/rootcastleengineering/sofia/raw/main/examples/basic_inference.py): Signal window packaging, 14-feature extraction, threshold anomaly detection, and evidence-based health scoring.
+- [`examples/signal_analysis.py`](https://huggingface.co/rootcastleengineering/sofia/raw/main/examples/signal_analysis.py): FFT magnitude, Welch PSD with Parseval energy conservation check, Hilbert analytic envelope, and Fortescue symmetrical components.
+- [`examples/edge_runtime.py`](https://huggingface.co/rootcastleengineering/sofia/raw/main/examples/edge_runtime.py): Bounded `SignalFrame`, Sofia Assembly VM execution, in-situ neural training step, and safe `sofia.model.v1` serialization.
+
+To execute the basic inference example:
+```bash
+python examples/basic_inference.py
+```
+
+---
+
+## 7. Model Manifests & Checkpoint Policy
+
+Hugging Face distribution files are machine-readable and schema-validated:
+
+- [`config.json`](https://huggingface.co/rootcastleengineering/sofia/raw/main/config.json): Runtime capabilities, Python version, and dependency requirements.
+- [`model_manifest.json`](https://huggingface.co/rootcastleengineering/sofia/raw/main/model_manifest.json): Conforms to [`schemas/model.schema.json`](https://huggingface.co/rootcastleengineering/sofia/raw/main/schemas/model.schema.json).
+- [`runtime_manifest.json`](https://huggingface.co/rootcastleengineering/sofia/raw/main/runtime_manifest.json): Exact Git commit SHA, dependency versions, latency budgets, and subsystem maturity.
+
+### Checkpoint Policy
+- **Zero-Pickle Invariant:** Model weights must be distributed in `.safetensors` or `.npz` format. Python `pickle` is strictly prohibited.
+- **Cryptographic Verification:** Every model artifact must declare its lowercase SHA-256 parameter digest.
+- See [`artifacts/README.md`](https://huggingface.co/rootcastleengineering/sofia/raw/main/artifacts/README.md) for full details.
+
+---
+
+## 8. Empirical Performance Benchmarks
+
+Measured on Profile A hardware (Intel64 x86_64, Windows 11, Python 3.12.10 CPython) across $N = 100$ iterations:
+
+| Metric | Measured $p_{50}$ | Target Budget | Result |
+| :--- | :--- | :--- | :--- |
+| **FFT / Welch PSD (1024 samples)** | **$307.6\,\mu\text{s}$** | $\le 500\,\mu\text{s}$ | **PASS** |
+| **FFT / Welch PSD (4096 samples)** | **$387.4\,\mu\text{s}$** | $\le 2000\,\mu\text{s}$ | **PASS** |
+| **Analytic Envelope (2048 samples)** | **$127.8\,\mu\text{s}$** | $\le 1000\,\mu\text{s}$ | **PASS** |
+| **Symmetrical Components (Fortescue)** | **$55.5\,\mu\text{s}$** | $\le 1500\,\mu\text{s}$ | **PASS** |
+| **Peak Memory Consumption** | **$7.14\text{ MB}$** | $\le 32\text{ MB}$ | **PASS** |
+
+Complete benchmark reports and JSON schema are available in [`benchmarks/`](https://huggingface.co/rootcastleengineering/sofia/tree/main/benchmarks).
+
+---
+
+## 9. Safety & Limitations
+
+- **Engineering Judgment:** Sofia Engine outputs are diagnostic aids. They do not replace physical inspection or qualified engineering sign-off.
+- **Physical Safety Interlocks:** Under no circumstance should AI or diagnostic outputs directly control machinery without external, hardware-certified safety interlocks (e.g. SIL relays).
+- **Sensor Calibration:** Diagnostic accuracy is bounded by sensor fidelity, mounting configuration, and signal acquisition quality.
+- Read [`docs/LIMITATIONS.md`](https://huggingface.co/rootcastleengineering/sofia/raw/main/docs/LIMITATIONS.md) and [`docs/SECURITY.md`](https://huggingface.co/rootcastleengineering/sofia/raw/main/docs/SECURITY.md) for detailed boundaries.
+
+---
+
+## 10. Citation
+
+To cite Sofia Engine in scientific software, publications, or engineering documentation:
+
+```bibtex
+@software{sofia_engine_2026,
+  author       = {{Rootcastle Engineering \& Innovation}},
+  title        = {Sofia Engine: Scientific \& Edge Intelligence Runtime},
+  year         = {2026},
+  version      = {3.0.0a1},
+  publisher    = {Hugging Face},
+  doi          = {10.57967/hf/10549},
+  url          = {https://huggingface.co/rootcastleengineering/sofia}
+}
+```

artifacts/README.md

@@ -0,0 +1,28 @@
+# Sofia Engine Checkpoint & Artifact Registry
+
+This directory defines the distribution and security policy for future trained Sofia model checkpoints and parameter sets.
+
+---
+
+## 1. Current Checkpoint Status
+
+> **Canonical Pretrained Checkpoint:** *Not yet released.*
+>
+> Sofia Engine 3.0.0a1 provides the runtime engine, feature extraction contracts, assembly virtual machine, and safe serialization interfaces. No pre-trained foundation model weights are shipped in this release.
+
+---
+
+## 2. Checkpoint Release Policy
+
+Every future checkpoint published under this repository must satisfy the following technical requirements:
+
+1. **Safe Serialization Formats**:
+   - Primary: `.safetensors` or validated `.npz` (via `np.savez`).
+   - **Prohibited:** Python `pickle` (`.pkl`, `.pickle`, `.pt` containing arbitrary executable code) is strictly forbidden.
+2. **Cryptographic Integrity**:
+   - Every artifact file must be accompanied by its lowercase SHA-256 digest (`parameters_sha256`).
+   - Manifests are verified before weights are mapped into memory.
+3. **Declared Feature Schema**:
+   - The checkpoint manifest must explicitly declare its input `feature_schema` (e.g., `vibration-v3`, `power-quality-v1`) to prevent feature order mismatches.
+4. **Transparent Provenance**:
+   - Public release notes must specify training dataset origin, sample count, evaluation metrics, and runtime version compatibility.

benchmarks/README.md

@@ -0,0 +1,28 @@
+# Sofia Engine Empirical Performance Benchmarks
+
+All benchmark metrics published below represent real measurements executed on physical test hardware using `benchmarks/run_benchmarks.py`. **No metrics are fabricated or estimated.**
+
+---
+
+## 1. Hardware Profile A Reference Measurements
+
+- **OS / Platform:** Windows 11 (AMD64)
+- **CPU:** Intel64 Family 6 Model 165 (x86_64)
+- **Python Version:** 3.12.10 CPython
+- **Timestamp:** 2026-09-21 23:56:41 UTC
+
+### Latency Percentiles ($N = 100$ iterations)
+
+| Benchmark Task | Target Budget | Mean | $p_{50}$ (Median) | $p_{95}$ | $p_{99}$ | Budget Status |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| **Package Import Time** | $\le 500\text{ ms}$ | $342.8\text{ ms}$ | — | — | — | **PASS** |
+| **FFT / Welch PSD (1024 samples)** | $\le 500\,\mu\text{s}$ | $319.2\,\mu\text{s}$ | **$307.6\,\mu\text{s}$** | $362.8\,\mu\text{s}$ | $445.5\,\mu\text{s}$ | **PASS** |
+| **FFT / Welch PSD (4096 samples)** | $\le 2000\,\mu\text{s}$ | $430.3\,\mu\text{s}$ | **$387.4\,\mu\text{s}$** | $597.3\,\mu\text{s}$ | $713.1\,\mu\text{s}$ | **PASS** |
+| **Analytic Envelope (2048 samples)** | $\le 1000\,\mu\text{s}$ | $141.0\,\mu\text{s}$ | **$127.8\,\mu\text{s}$** | $200.2\,\mu\text{s}$ | $237.9\,\mu\text{s}$ | **PASS** |
+| **Symmetrical Components (Fortescue)**| $\le 1500\,\mu\text{s}$ | $60.7\,\mu\text{s}$ | **$55.5\,\mu\text{s}$** | $93.0\,\mu\text{s}$ | $102.7\,\mu\text{s}$ | **PASS** |
+| **14-Feature Extraction (1024 samples)**| $\le 10000\,\mu\text{s}$| $2521.5\,\mu\text{s}$| **$2415.5\,\mu\text{s}$**| $3304.8\,\mu\text{s}$| $3491.0\,\mu\text{s}$| **PASS** |
+| **Sofia VM Forward Inference (4→8→1)**| $\le 5000\,\mu\text{s}$| $1751.2\,\mu\text{s}$| **$1675.8\,\mu\text{s}$**| $2210.2\,\mu\text{s}$| $2457.1\,\mu\text{s}$| **PASS** |
+| **Sofia VM Training Step (analytical backprop)**| $\le 20000\,\mu\text{s}$| $6609.7\,\mu\text{s}$| **$6442.9\,\mu\text{s}$**| $7483.0\,\mu\text{s}$| $9051.6\,\mu\text{s}$| **PASS** |
+
+### Memory Consumption
+- Peak traced memory during benchmark suite: **$7.14\text{ MB}$** ($\le 32\text{ MB}$ budget for Profile A gateways).

benchmarks/benchmark-schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://huggingface.co/rootcastleengineering/sofia/raw/main/benchmarks/benchmark-schema.json",
+  "title": "SofiaBenchmarkReport",
+  "description": "Schema for Sofia Engine empirical benchmark execution reports.",
+  "type": "object",
+  "properties": {
+    "timestamp_utc": { "type": "string", "format": "date-time" },
+    "environment": {
+      "type": "object",
+      "properties": {
+        "os": { "type": "string" },
+        "machine": { "type": "string" },
+        "processor": { "type": "string" },
+        "python_version": { "type": "string" }
+      },
+      "required": ["os", "python_version"]
+    },
+    "benchmarks": {
+      "type": "object",
+      "properties": {
+        "import_time_ms": { "type": "number" },
+        "fft_psd_1024": { "$ref": "#/$defs/stat_record" },
+        "fft_psd_4096": { "$ref": "#/$defs/stat_record" },
+        "analytic_envelope_2048": { "$ref": "#/$defs/stat_record" },
+        "feature_extraction_1024": { "$ref": "#/$defs/stat_record" },
+        "electrical_symmetrical_components": { "$ref": "#/$defs/stat_record" }
+      },
+      "required": ["import_time_ms"]
+    },
+    "memory": {
+      "type": "object",
+      "properties": {
+        "current_traced_kb": { "type": "number" },
+        "peak_traced_kb": { "type": "number" }
+      }
+    }
+  },
+  "required": ["timestamp_utc", "environment", "benchmarks"],
+  "$defs": {
+    "stat_record": {
+      "type": "object",
+      "properties": {
+        "n_iterations": { "type": "integer" },
+        "mean_us": { "type": "number" },
+        "p50_us": { "type": "number" },
+        "p95_us": { "type": "number" },
+        "p99_us": { "type": "number" },
+        "min_us": { "type": "number" },
+        "max_us": { "type": "number" }
+      },
+      "required": ["n_iterations", "mean_us", "p50_us"]
+    }
+  }
+}

config.json

@@ -0,0 +1,27 @@
+{
+  "model_type": "sofia-engine",
+  "architecture": "scientific-edge-runtime",
+  "library_name": "sofia-engine",
+  "runtime": {
+    "version": "3.0.0a1",
+    "python": ">=3.11",
+    "core_dependency": "numpy>=1.24",
+    "offline_first": true,
+    "deterministic": true
+  },
+  "capabilities": {
+    "scientific_signal_processing": true,
+    "industrial_telemetry": true,
+    "machine_health_diagnostics": true,
+    "embedded_c_runtime": true,
+    "assembly_virtual_machine": "beta",
+    "on_device_learning": "experimental",
+    "quantum_emulation": "experimental",
+    "llm_copilot": "optional"
+  },
+  "publisher": {
+    "organization": "Rootcastle Engineering & Innovation",
+    "website": "https://rootcastle.com/",
+    "source_repository": "https://github.com/rootcastleco/sofia-ai"
+  }
+}

docs/ARCHITECTURE.md

@@ -0,0 +1,51 @@
+# Sofia Engine Runtime Architecture
+
+Sofia Engine is structured as a unidirectional, 10-layer deterministic pipeline designed for scientific telemetry processing, machine condition monitoring, and bounded edge intelligence.
+
+---
+
+## 1. Unidirectional Data Flow
+
+The runtime enforces strict layer boundaries. Dependencies only point downwards; higher-level diagnostics or advisory copilots never feed uncontrolled state back into deterministic signal processing.
+
+```mermaid
+flowchart LR
+    S["Physical Sensors"] --> I["Telemetry Ingestion"]
+    I --> Q["Validation & Signal Quality"]
+    Q --> B["Bounded Buffers"]
+    B --> D["Scientific DSP"]
+    D --> F["Versioned Feature Vector"]
+    F --> M["Inference Backends"]
+    M --> E["Evidence Fusion"]
+    E --> H["Diagnostics & Health"]
+    H --> P["Policy Engine"]
+    P --> O["Advisory / Controlled Output"]
+```
+
+---
+
+## 2. Layer Definitions
+
+| Layer | Component | Responsibility | Contracts & Invariants |
+| :--- | :--- | :--- | :--- |
+| **0** | **Physical Sensors** | Piezoelectric accelerometers, voltage/current transducers, RTDs, pressure sensors | Raw electrical quantities ($V, mA, mV/g$) |
+| **1** | **Telemetry Ingestion** | Packaging time-series samples into bounded frames | `SignalMetadata`, `SignalFrame` ($\le 65536$ capacity ceiling) |
+| **2** | **Validation & Quality** | Quality flagging (`GOOD`, `DEGRADED`, `UNCERTAIN`, `INVALID`, `SATURATED`) | IEEE 754 non-finite check; timestamp plausibility |
+| **3** | **Bounded Buffers** | Deterministic circular ring buffers | Static allocation; zero dynamic growth post-init |
+| **4** | **Scientific DSP** | FFT, Welch PSD, Hilbert analytic envelope, Fortescue symmetrical components | Parseval energy conservation; frequency axis from $f_s$, not wall-clock |
+| **5** | **Feature Extraction** | Statistical, spectral, and domain feature extraction | `FeatureVector` (Schema v3.0, ordered fixed tuple, unit-bearing) |
+| **6** | **Inference Backends** | Anomaly detectors, linear models, Assembly Neural Network | `ModelBackend` interface, manifest checksum enforcement |
+| **7** | **Evidence Fusion** | Combining detection signals into versioned evidence bundles | `EvidenceBundle`, Noisy-OR confidence aggregation |
+| **8** | **Diagnostics & Health** | Machine health evaluation, uncertainty interval calculation | `HealthScore` ($0-100 \pm \Delta$), `DiagnosticEngine` |
+| **9** | **Safety & Policy** | Command authorization, replay protection, interlock gating | Default DENY posture, Nonce + TTL replay guard |
+| **10** | **Advisory Output** | Diagnostic reports, telemetry export, advisory LLM copilot | **LLMs are strictly advisory; isolated from machine actuation** |
+
+---
+
+## 3. Cross-Language Conformance
+
+Sofia Engine maintains verified mathematical consistency across three target implementations:
+
+1. **Python (`sofia_ai`)**: Reference scientific implementation for gateways, edge servers, and cloud pipelines (NumPy-based, zero heavy framework dependencies).
+2. **TypeScript (`@rootcastle/sofia-engine`)**: Edge gateway, industrial browser, and Node.js runtimes with identical statistical contracts.
+3. **C99 Embedded (`embedded/`)**: Microcontroller target (ARM Cortex-M, RISC-V) featuring zero heap allocation post-init (`malloc` prohibited) and Q16.16 fixed-point arithmetic.

docs/LIMITATIONS.md

@@ -0,0 +1,24 @@
+# Sofia Engine Operating Boundaries & Transparent Limitations
+
+In accordance with our engineering principle **"Evidence beats claims"**, the following boundaries and limitations apply to Sofia Engine 3.0.0a1:
+
+---
+
+## 1. Checkpoint Distribution Status
+- **No Canonical Pretrained Foundation Model:**
+  Sofia Engine 3.0.0a1 is a **Scientific & Edge Intelligence Runtime**, not a foundation model. No pre-trained neural checkpoint is distributed in this initial release.
+  Future trained checkpoints (e.g. bearing fault classifiers, transformer-based time-series anomaly models) will be distributed with explicit training provenance, evaluation reports, and SHA-256 digests.
+
+## 2. Hardware & Fixed-Point Numerical Differences
+- **C99 vs. Python Floating-Point:**
+  The Python runtime operates in IEEE 754 double precision (64-bit float). The C99 embedded reference engine supports both single precision (32-bit float) and Q16.16 fixed-point arithmetic. Fixed-point computations have a finite resolution of $\approx 1.526 \times 10^{-5}$ and may exhibit small truncation differences compared to 64-bit float baselines.
+
+## 3. Standards Compliance Scope
+- **Relevance vs. Formal Certification:**
+  Sofia Engine implements calculations relevant to industrial standards (e.g., ISO 10816/20816 vibration severity zones, IEEE 519 harmonic limits, IEC 61000-4-30 power quality concepts). **Software implementation does not constitute formal device or system-level certification.** Certified deployments require end-to-end hardware calibration and formal test laboratory certification.
+
+## 4. Operational Safety Notice
+- **Non-Replacement of Qualified Engineering Judgment:**
+  Diagnostic outputs (Health Scores, Severity classifications, Anomaly events) are mathematical inferences based strictly on incoming sensor telemetry. They do not replace certified human inspection or qualified engineering judgment.
+- **Physical Safety Interlocks:**
+  Sofia Engine outputs must never be connected directly to emergency stops, circuit breakers, or critical plant actuators without independent, hardwired, safety-certified physical interlocks (e.g. SIL-rated safety relays).

docs/SCIENTIFIC_VALIDATION.md

@@ -0,0 +1,51 @@
+# Sofia Engine Scientific Validation
+
+All algorithms in Sofia Engine are backed by deterministic mathematical verification, golden test vectors, and physical conservation laws.
+
+---
+
+## 1. Digital Signal Processing Correctness
+
+### Parseval Energy Conservation
+For discrete signals, Parseval's theorem dictates that total energy in the time domain must equal total energy in the frequency domain:
+$$\sum_{n=0}^{N-1} |x[n]|^2 = \frac{1}{N} \sum_{k=0}^{N-1} |X[k]|^2$$
+
+When applying window functions $w[n]$, energy is attenuated by the noise power bandwidth gain:
+$$S_2 = \sum_{n=0}^{N-1} w[n]^2$$
+
+Sofia's `welch_psd` implementation normalizes power spectral density by $S_2$ and frequency resolution $\Delta f = f_s / N$. Energy conservation across Hann, Hamming, and Blackman windows is continuously verified in `tests/unit/test_dsp_golden.py`:
+$$\left| \frac{\int \text{PSD}(f)\,df}{\text{Var}(x)} - 1.0 \right| < 0.05$$
+
+### Exact Amplitude Recovery
+For unwindowed integer-bin tones ($f_0 = k \cdot f_s / N$), the one-sided FFT magnitude recovers the exact continuous amplitude $A$:
+$$\hat{A} = \frac{2}{N} |X[k]|$$
+Sofia verifies peak tone amplitude recovery to machine precision ($< 10^{-14}$ relative error).
+
+### 3-Phase Symmetrical Components (Fortescue Transformation)
+Unbalanced 3-phase voltages $V_a, V_b, V_c$ are decomposed using the complex operator $a = e^{j 120^\circ} = -\frac{1}{2} + j \frac{\sqrt{3}}{2}$:
+$$\begin{bmatrix} V_0 \\ V_1 \\ V_2 \end{bmatrix} = \frac{1}{3} \begin{bmatrix} 1 & 1 & 1 \\ 1 & a & a^2 \\ 1 & a^2 & a \end{bmatrix} \begin{bmatrix} V_a \\ V_b \\ V_c \end{bmatrix}$$
+$$\text{VUF} = \frac{|V_2|}{|V_1|} \times 100\%$$
+Golden vectors generated in `tests/golden/dsp_golden.json` assert that positive ($V_1$), negative ($V_2$), and zero ($V_0$) sequence components match theoretical values within $10^{-5}$ tolerance across Python, TypeScript, and C99 runtimes.
+
+---
+
+## 2. In-Situ Neural Training & Gradient Verification
+
+Sofia's virtual assembly neural network (`AssemblyNeuralNetwork`) implements 2-layer analytical backpropagation directly in virtual bytecode:
+$$\frac{\partial L}{\partial W_2} = \frac{\partial L}{\partial \hat{y}} \cdot h^T, \quad \frac{\partial L}{\partial B_2} = \frac{\partial L}{\partial \hat{y}}$$
+$$\frac{\partial L}{\partial h} = W_2^T \cdot \frac{\partial L}{\partial \hat{y}}, \quad \frac{\partial L}{\partial z_1} = \frac{\partial L}{\partial h} \odot \mathbb{I}(z_1 > 0)$$
+$$\frac{\partial L}{\partial W_1} = \frac{\partial L}{\partial z_1} \cdot x^T, \quad \frac{\partial L}{\partial B_1} = \frac{\partial L}{\partial z_1}$$
+
+Analytical gradients computed in virtual registers are validated against central finite differences:
+$$\frac{\partial L}{\partial \theta_i} \approx \frac{L(\theta_i + \epsilon) - L(\theta_i - \epsilon)}{2\epsilon}, \quad \epsilon = 10^{-5}$$
+The relative error $\frac{\|\nabla_{\text{analytical}} - \nabla_{\text{numerical}}\|}{\|\nabla_{\text{analytical}}\| + \|\nabla_{\text{numerical}}\|}$ is proven to be $< 10^{-5}$ in `tests/unit/test_neural_gradients.py`.
+
+---
+
+## 3. Microcontroller Fixed-Point Conformance
+
+The C99 embedded runtime (`embedded/src/sofia_features.c`) implements Q16.16 fixed-point arithmetic:
+- Fixed-point resolution: $1/65536 \approx 1.526 \times 10^{-5}$
+- Dynamic range: $[-32768.0, +32767.99998]$
+- Zero heap allocation: no calls to `malloc`, `calloc`, or `free` post-initialization.
+- Compile-time static ceilings: `SOFIA_MAX_FFT_LEN = 1024`, `SOFIA_N_STAT_FEATURES = 14`.

docs/SECURITY.md

@@ -0,0 +1,30 @@
+# Sofia Engine Security Architecture & Threat Model
+
+Sofia Engine is designed under the assumption that edge and industrial environments operate under adversarial and untrusted network conditions.
+
+---
+
+## 1. Core Security Invariants
+
+1. **Default DENY Posture**:
+   The `PolicyEngine` rejects all incoming actuation commands by default. An explicit, cryptographically authenticated rule must permit execution.
+2. **Replay Protection**:
+   All commands require a unique Nonce, monotonic Sequence Number, and Time-To-Live (TTL). Replayed commands or expired timestamps are immediately rejected.
+3. **LLM Actuation Firewall**:
+   External AI models (e.g. OpenAI, Anthropic, NVIDIA NIM, local LLMs) are strictly categorized as **Advisory Copilots**. Under no circumstance can an LLM directly trigger an edge actuator or override safety interlocks.
+4. **Zero-Pickle Artifacts**:
+   Sofia models are serialized exclusively as JSON manifests + NPZ/safetensors weight archives with SHA-256 parameter hashing. Arbitrary Python pickle files are strictly rejected.
+5. **Secret Scrubbing**:
+   All tokens, API keys, credentials, and sensitive headers are redacted from debug logs and telemetry exports using pattern-matched redaction filters.
+
+---
+
+## 2. Threat Mitigations
+
+| Threat | Impact | Sofia Runtime Mitigation |
+| :--- | :--- | :--- |
+| **Command Injection / Replay** | Unauthorized machine actuation | `ReplayGuard` with Nonce cache, monotonic timestamp validation, and TTL eviction |
+| **Model Tampering** | Adversarial parameter alteration | Mandatory SHA-256 parameter hash verification in `ModelManifest` prior to loading |
+| **Sensor Saturation / Clipping** | Corrupted diagnostic assessment | `DataQuality.SATURATED` flag automatically attenuates diagnostic confidence to $\le 0.20$ |
+| **Memory Exhaustion** | Gateway denial-of-service | Static capacity ceilings ($\le 65536$ frame size, fixed circular buffers, zero dynamic allocation in C99) |
+| **Hostile Telemetry Metadata** | Buffer overflow or script injection | Strict identifier sanitization (`^[a-zA-Z0-9_\-\.]{1,64}$`) on all channels and device IDs |

examples/basic_inference.py

@@ -0,0 +1,103 @@
+"""Basic Inference Example for Sofia Engine.
+
+Demonstrates deterministic telemetry feature extraction, statistical anomaly
+detection, and evidence-based diagnostic health scoring.
+
+Run:
+    python examples/basic_inference.py
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from sofia_ai.core.contracts import DataQuality, FeatureVector, SignalWindow
+from sofia_ai.diagnostics.engine import (
+    DiagnosticEngine,
+    HealthEvent,
+    HealthScore,
+    compute_health_score,
+)
+from sofia_ai.diagnostics.rules import RuleContext
+from sofia_ai.features import extract_from_array
+from sofia_ai.inference.detectors import ThresholdDetector, build_manifest_for
+
+
+def run_basic_inference() -> None:
+    print("=== Sofia Engine: Basic Inference Example ===")
+
+    # 1. Synthesize 1 second of vibration telemetry (fs = 1000 Hz, 25 Hz shaft rotation)
+    fs = 1000.0
+    t = np.arange(1000) / fs
+    rng = np.random.default_rng(42)
+    # 25 Hz fundamental + 50 Hz harmonic + Gaussian background noise
+    raw_signal = (
+        0.45 * np.sin(2 * np.pi * 25.0 * t)
+        + 0.15 * np.sin(2 * np.pi * 50.0 * t)
+        + 0.05 * rng.normal(size=len(t))
+    )
+
+    print(f"Input Signal: {len(raw_signal)} samples @ {fs} Hz ({len(raw_signal)/fs:.2f} s)")
+
+    # 2. Package into a validated SignalWindow
+    window = SignalWindow(
+        values=raw_signal,
+        sample_rate=fs,
+        device_id="pump-motor-01",
+        channel="vibration_de",
+        unit="m/s^2",
+        quality=DataQuality.GOOD,
+    )
+
+    # 3. Extract versioned feature vector (14 statistical + spectral metrics)
+    features: FeatureVector = extract_from_array(
+        window.values,
+        window.sample_rate,
+        channel=window.channel,
+        quality=window.quality,
+    )
+
+    # 4. Verify feature schema version (v3.0)
+    features.validate_schema("3.0")
+    print(f"Extracted FeatureVector (schema {features.schema_version}): {len(features.names)} features")
+    for name, val in list(zip(features.names, features.values, strict=True))[:5]:
+        print(f"  - {name}: {val:.4f}")
+
+    # 5. Anomaly detection via ThresholdDetector (monitoring vibration RMS)
+    detector = ThresholdDetector(feature="rms", high=0.45)
+    manifest = build_manifest_for(detector, model_id="rms_threshold_v1", version="1.0.0")
+    detector.load(manifest)
+    inference_result = detector.infer(features)
+
+    print("\n--- Inference Result (Threshold Detector) ---")
+    print(f"Monitored Feature: 'rms' = {inference_result.score:.4f} m/s^2 (high limit = 0.45)")
+    print(f"Outcome:           {inference_result.outcome.name}")
+    print(f"Confidence:        {inference_result.confidence:.2%}")
+
+    # 6. Diagnostic Engine: Convert inference into evidence-backed health event
+    diag_engine = DiagnosticEngine()
+    context = RuleContext(
+        device_id=window.device_id,
+        channel=window.channel,
+        score=inference_result.score,
+        confidence=inference_result.confidence,
+        unit="z-score",
+    )
+    event: HealthEvent | None = diag_engine.evaluate(context)
+
+    events = [event] if event else []
+    health_score: HealthScore = compute_health_score(events)
+
+    print("\n--- Health Assessment ---")
+    print(f"Health Score:      {health_score.score:.1f} / 100.0")
+    print(f"Credible Interval: [{health_score.lower:.1f}, {health_score.upper:.1f}]")
+    print(f"Uncertainty:       ±{health_score.uncertainty:.2%}")
+    if event:
+        print(f"Health Event:      {event.event_type} (Severity: {event.severity.name})")
+        print(f"Recommendation:    {event.recommendation}")
+    else:
+        print("Status:            Nominal operating condition.")
+
+
+if __name__ == "__main__":
+    run_basic_inference()

examples/edge_runtime.py

@@ -0,0 +1,144 @@
+"""Edge Runtime Example for Sofia Engine.
+
+Demonstrates:
+1. Memory-bounded SignalFrame telemetry packaging
+2. Hardened Sofia Assembly VM bytecode execution
+3. In-situ neural network forward pass & analytical backpropagation
+4. Safe, zero-pickle model serialization (JSON manifest + NPZ + SHA-256)
+
+Run:
+    python examples/edge_runtime.py
+"""
+
+from __future__ import annotations
+
+import tempfile
+import time
+from pathlib import Path
+import numpy as np
+
+from sofia_ai.core.contracts import DataQuality, Sample, SignalFrame, SignalMetadata
+from sofia_ai.learning.asm import AssemblyNeuralNetwork
+from sofia_ai.learning.asm.vm import (
+    AsmInstruction,
+    OpCode,
+    Register,
+    SofiaAsmVM,
+    VMStatus,
+)
+from sofia_ai.learning.manifest import load_assembly_model, save_assembly_model
+
+
+def run_edge_runtime() -> None:
+    print("=== Sofia Engine: Edge Runtime & Embedded VM ===")
+
+    # -------------------------------------------------------------------------
+    # 1. Bounded SignalFrame Telemetry Packaging
+    # -------------------------------------------------------------------------
+    fs = 1000.0
+    meta = SignalMetadata(
+        sample_rate=fs,
+        channel_name="vibration_radial",
+        physical_unit="m/s^2",
+        sensor_id="piezo_accel_42",
+    )
+
+    # Telemetry buffer strictly respects runtime capacity ceilings (<= 65536)
+    base_time = time.time()
+    samples = tuple(
+        Sample(
+            timestamp=base_time + i / fs,
+            device_id="edge-gateway-42",
+            channel="vibration_radial",
+            value=float(np.sin(2 * np.pi * 10.0 * (i / fs))),
+            unit="m/s^2",
+            quality=DataQuality.GOOD,
+        )
+        for i in range(256)
+    )
+    frame = SignalFrame(samples=samples, metadata=meta)
+
+    print(f"\n[1] SignalFrame Ingested: {frame.size} samples, Quality={frame.samples[0].quality.name}")
+    print(f"    Channel: {frame.metadata.channel_name}, Sensor: {frame.metadata.sensor_id}")
+
+    # -------------------------------------------------------------------------
+    # 2. Hardened Sofia Assembly Virtual Machine
+    # -------------------------------------------------------------------------
+    print("\n[2] Sofia Assembly Virtual Machine Execution")
+    vm = SofiaAsmVM(memory_size=1024)
+
+    # Assemble a bounded test program:
+    # R1 = 12.5, R2 = 3.5, R1 = R1 + R2 (16.0), Mem[100] = R1, HALT
+    program = [
+        AsmInstruction(OpCode.LOAD_CONST, Register.R1, imm=12.5),
+        AsmInstruction(OpCode.LOAD_CONST, Register.R2, imm=3.5),
+        AsmInstruction(OpCode.ADD, Register.R1, Register.R2),
+        AsmInstruction(OpCode.LOAD_CONST, Register.R3, imm=100.0),
+        AsmInstruction(OpCode.STORE_MEM, Register.R3, Register.R1),
+        AsmInstruction(OpCode.HALT),
+    ]
+
+    result = vm.run(program, max_cycles=1000)
+    print(f"    VM Status:       {result.status.value}")
+    print(f"    Executed Cycles: {result.cycles}")
+    print(f"    Register R1:     {vm.registers[Register.R1]:.2f}")
+    print(f"    Memory[100]:     {vm.memory[100]:.2f}")
+    assert result.status == VMStatus.HALTED
+    assert vm.memory[100] == 16.0
+
+    # -------------------------------------------------------------------------
+    # 3. In-Situ Neural Training with Analytical Backpropagation
+    # -------------------------------------------------------------------------
+    print("\n[3] In-Situ Neural Network (2-Layer Bytecode Backpropagation)")
+    input_dim, hidden_dim, output_dim = 4, 8, 1
+    net = AssemblyNeuralNetwork(
+        input_dim=input_dim,
+        hidden_dim=hidden_dim,
+        output_dim=output_dim,
+        learning_rate=0.05,
+    )
+
+    # Synthetic training sample (e.g. 4 normalized vibration features -> target health)
+    x = np.array([0.25, 0.40, 0.10, 0.60], dtype=np.float64)
+    target = np.array([0.85], dtype=np.float64)
+
+    initial_pred = net.forward(x)
+    initial_loss = float(np.mean((initial_pred - target) ** 2))
+    print(f"    Initial Prediction: {initial_pred[0]:.4f} (Target: {target[0]:.4f}, Loss: {initial_loss:.4f})")
+
+    # Perform 15 in-situ gradient update steps
+    for _ in range(15):
+        net.train_step(x, target)
+
+    final_pred = net.forward(x)
+    final_loss = float(np.mean((final_pred - target) ** 2))
+    print(f"    Updated Prediction: {final_pred[0]:.4f} (Target: {target[0]:.4f}, Loss: {final_loss:.4f})")
+    assert final_loss < initial_loss, "Loss should decrease after training steps"
+
+    # -------------------------------------------------------------------------
+    # 4. Safe Model Manifest Export & SHA-256 Checksum Verification
+    # -------------------------------------------------------------------------
+    print("\n[4] Safe Model Serialization (Zero-Pickle sofia.model.v1)")
+    with tempfile.TemporaryDirectory() as tmpdir:
+        manifest_path = save_assembly_model(
+            model=net,
+            destination_dir=tmpdir,
+            model_name="edge_demo_model",
+            feature_schema="vibration-v3",
+            extra_metadata={"trained_on": "synthetic_edge_sample"},
+        )
+        print(f"    Saved Manifest: {manifest_path.name}")
+
+        # Reload model and verify SHA-256 parameter integrity
+        loaded_net, loaded_manifest = load_assembly_model(manifest_path)
+        print(f"    Verified SHA-256: {loaded_manifest.parameters_sha256[:16]}... (Valid)")
+
+        reloaded_pred = loaded_net.forward(x)
+        print(f"    Reloaded Model Prediction: {reloaded_pred[0]:.4f}")
+        assert np.isclose(reloaded_pred[0], final_pred[0]), "Reloaded model must match original weights"
+
+    print("\nAll edge runtime checks passed successfully.")
+
+
+if __name__ == "__main__":
+    run_edge_runtime()

examples/signal_analysis.py

@@ -0,0 +1,92 @@
+"""Scientific Signal Analysis Example for Sofia Engine.
+
+Demonstrates deterministic digital signal processing across mechanical vibration
+and industrial electrical domains:
+1. FFT magnitude spectrum & peak detection
+2. Welch power spectral density & Parseval energy conservation
+3. Hilbert transform analytic amplitude envelope
+4. Fortescue 3-phase symmetrical components & Voltage Unbalance Factor (VUF)
+
+Run:
+    python examples/signal_analysis.py
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from sofia_ai.signal.electrical import compute_symmetrical_components
+from sofia_ai.signal.envelope import amplitude_envelope
+from sofia_ai.signal.spectral import peak_frequency, rfft_magnitude, welch_psd
+
+
+def run_signal_analysis() -> None:
+    print("=== Sofia Engine: Scientific Signal Analysis ===")
+
+    # -------------------------------------------------------------------------
+    # 1. Vibration Spectral Analysis (FFT & Welch PSD)
+    # -------------------------------------------------------------------------
+    fs = 2000.0  # 2 kHz sampling rate
+    n = 2000    # 1 second duration
+    t = np.arange(n) / fs
+
+    # Synthesize multi-tone machine vibration:
+    # 50 Hz shaft rotation (0.8 m/s^2) + 250 Hz gear-mesh tone (0.3 m/s^2)
+    tone_50 = 0.8 * np.sin(2 * np.pi * 50.0 * t)
+    tone_250 = 0.3 * np.sin(2 * np.pi * 250.0 * t)
+    noise = 0.05 * np.random.default_rng(123).normal(size=n)
+    signal = tone_50 + tone_250 + noise
+
+    print(f"\n[1] Vibration Telemetry ({n} samples @ {fs} Hz)")
+
+    # Compute FFT magnitude spectrum
+    spec = rfft_magnitude(signal, fs, window="hann", detrend_mean=True)
+    f_peak = peak_frequency(spec.frequencies, spec.values)
+    mag_peak = float(np.max(spec.values))
+    print(f"  FFT Peak Frequency: {f_peak:.1f} Hz (Magnitude: {mag_peak:.4f})")
+
+    # Compute Welch PSD
+    psd = welch_psd(signal, fs, segment_length=512, overlap=0.5, window="hann")
+    # Parseval check: integral of PSD approx equals variance of signal
+    signal_variance = float(np.var(signal))
+    psd_total_power = psd.total_power
+    parseval_ratio = psd_total_power / max(signal_variance, 1e-12)
+
+    print(f"  Welch PSD Total Power: {psd_total_power:.4f}")
+    print(f"  Time-Domain Variance:  {signal_variance:.4f}")
+    print(f"  Parseval Energy Ratio: {parseval_ratio:.4f} (expected ~1.0)")
+
+    # -------------------------------------------------------------------------
+    # 2. Bearing Fault Envelope Demodulation (Hilbert Transform)
+    # -------------------------------------------------------------------------
+    print("\n[2] Amplitude Demodulation (Hilbert Analytic Envelope)")
+    # Amplitude modulated signal: 200 Hz carrier modulated at 15 Hz fault pass frequency
+    carrier_freq = 200.0
+    mod_freq = 15.0
+    envelope_true = 1.0 + 0.6 * np.cos(2 * np.pi * mod_freq * t)
+    am_signal = envelope_true * np.cos(2 * np.pi * carrier_freq * t)
+
+    env = amplitude_envelope(am_signal)
+    env_spec = rfft_magnitude(env - np.mean(env), fs, window="hann")
+    env_peak_f = peak_frequency(env_spec.frequencies, env_spec.values)
+    print(f"  Extracted Modulation Frequency: {env_peak_f:.1f} Hz (expected {mod_freq:.1f} Hz)")
+
+    # -------------------------------------------------------------------------
+    # 3. 3-Phase Symmetrical Components (Fortescue Transformation)
+    # -------------------------------------------------------------------------
+    print("\n[3] 3-Phase Symmetrical Components (IEC / IEEE 519 analysis)")
+    # Unbalanced 3-phase voltages (Va=230V @ 0°, Vb=220V @ -125°, Vc=215V @ 115°)
+    sym = compute_symmetrical_components(
+        va_amp=230.0, va_phase_deg=0.0,
+        vb_amp=220.0, vb_phase_deg=-125.0,
+        vc_amp=215.0, vc_phase_deg=115.0,
+    )
+
+    print(f"  Positive Sequence (V1): {sym.v1_pos_seq_v:.2f} V")
+    print(f"  Negative Sequence (V2): {sym.v2_neg_seq_v:.2f} V")
+    print(f"  Zero Sequence (V0):     {sym.v0_zero_seq_v:.2f} V")
+    print(f"  Voltage Unbalance Factor (VUF): {sym.vuf_percent:.2f}%")
+
+
+if __name__ == "__main__":
+    run_signal_analysis()

model_manifest.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://huggingface.co/rootcastleengineering/sofia/raw/main/schemas/model.schema.json",
+  "schema": "sofia.model-manifest.v1",
+  "name": "Sofia Engine",
+  "publisher": "Rootcastle Engineering & Innovation",
+  "license": "Apache-2.0",
+  "source_repository": "https://github.com/rootcastleco/sofia-ai",
+  "artifact_type": "scientific-edge-runtime",
+  "version": "3.0.0a1",
+  "checkpoint": null,
+  "feature_schema": "3.0",
+  "parameters_sha256": null,
+  "training": {
+    "trained": false,
+    "dataset": null,
+    "metrics": null,
+    "note": "No canonical pretrained checkpoint is distributed with this runtime release."
+  },
+  "provenance": {
+    "git_commit": "3f1d5e85f8ab66870168f185a74bc80790926214",
+    "release": "3.0.0a1",
+    "timestamp_utc": "2026-09-22T00:03:00Z"
+  }
+}

releases/README.md

@@ -0,0 +1,23 @@
+# Sofia Engine Release Provenance
+
+Every artifact distributed on Hugging Face is linked to a deterministic release commit on GitHub.
+
+---
+
+## Current Release: `3.0.0a1`
+
+- **Release Date:** 2026-09-22
+- **Canonical Repository:** [rootcastleco/sofia-ai](https://github.com/rootcastleco/sofia-ai)
+- **Git Branch:** `feature/sofia-runtime-v3`
+- **Git Commit SHA:** `3f1d5e85f8ab66870168f185a74bc80790926214`
+- **PyPI Distribution Package:** `sofia-engine == 3.0.0a1`
+- **npm TypeScript SDK Package:** `@rootcastle/sofia-engine @ 3.0.0a1`
+- **DOI:** `10.57967/hf/10549`
+- **Feature Vector Schema Version:** `3.0`
+- **Model Manifest Schema Version:** `sofia.model-manifest.v1`
+- **Quality Gates Passed:**
+  - `pytest`: 898 passed, 1 skipped (`torch` optional), 0 failed
+  - `node --test`: 4 passed, 0 failed
+  - `ruff`: 0 errors
+  - `mypy`: 0 errors (strict mode across 91 files)
+  - `verification-matrix.md`: 49 / 49 requirements PASS

runtime_manifest.json

@@ -0,0 +1,44 @@
+{
+  "schema": "sofia.runtime-manifest.v1",
+  "name": "Sofia Engine",
+  "version": "3.0.0a1",
+  "release_date": "2026-09-22",
+  "provenance": {
+    "git_commit": "3f1d5e85f8ab66870168f185a74bc80790926214",
+    "repository": "https://github.com/rootcastleco/sofia-ai",
+    "branch": "feature/sofia-runtime-v3"
+  },
+  "runtime_environment": {
+    "python": ">=3.11",
+    "dependencies": {
+      "core": ["numpy>=1.24"],
+      "optional_industrial": ["paho-mqtt>=1.6", "pymodbus>=3.0", "pyserial>=3.5"],
+      "optional_ml": ["onnxruntime>=1.15", "torch>=2.0"],
+      "optional_copilot": ["openai>=1.0"]
+    },
+    "supported_architectures": ["x86_64", "arm64", "armv7l", "c99-embedded"]
+  },
+  "contracts": {
+    "feature_vector_schema": "3.0",
+    "model_manifest_schema": "sofia.model-manifest.v1",
+    "vm_bytecode_version": "1.0",
+    "embedded_q_format": "Q16.16"
+  },
+  "performance_budgets": {
+    "fft_1024_us_ceiling": 500,
+    "fft_4096_us_ceiling": 2000,
+    "envelope_2048_us_ceiling": 1000,
+    "symmetrical_components_us_ceiling": 1500
+  },
+  "subsystem_maturity": {
+    "scientific_dsp": "stable",
+    "telemetry_runtime": "stable",
+    "diagnostics_engine": "stable",
+    "policy_engine": "stable",
+    "embedded_c99": "stable",
+    "assembly_vm": "beta",
+    "in_situ_learning": "experimental",
+    "quantum_emulation": "experimental",
+    "llm_copilot": "optional"
+  }
+}

schemas/feature-vector.schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://huggingface.co/rootcastleengineering/sofia/raw/main/schemas/feature-vector.schema.json",
+  "title": "SofiaFeatureVector",
+  "description": "Schema for Sofia Engine ordered, named, unit-bearing feature vectors (Schema v3.0).",
+  "type": "object",
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "enum": ["3.0"]
+    },
+    "extractor_id": {
+      "type": "string"
+    },
+    "extractor_version": {
+      "type": "string"
+    },
+    "source_channel": {
+      "type": "string"
+    },
+    "sample_rate": {
+      "type": "number",
+      "minimum": 0
+    },
+    "quality": {
+      "type": "string",
+      "enum": ["GOOD", "DEGRADED", "UNCERTAIN", "INVALID", "STALE", "SATURATED"]
+    },
+    "names": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "values": {
+      "type": "array",
+      "items": { "type": "number" }
+    },
+    "uncertainties": {
+      "type": "array",
+      "items": { "type": "number", "minimum": 0 }
+    },
+    "features": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": { "type": "string" },
+          "value": { "type": "number" },
+          "unit": { "type": "string" },
+          "uncertainty": { "type": "number", "minimum": 0 },
+          "quality": { "type": "string" },
+          "algorithm": { "type": "string" },
+          "algorithm_version": { "type": "string" }
+        },
+        "required": ["name", "value", "unit"]
+      }
+    },
+    "metadata": {
+      "type": "object"
+    }
+  },
+  "required": ["schema_version", "extractor_id", "extractor_version", "names", "values"]
+}

schemas/model.schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://huggingface.co/rootcastleengineering/sofia/raw/main/schemas/model.schema.json",
+  "title": "SofiaModelManifest",
+  "description": "Schema for Sofia Engine model artifacts, checkpoints, and parameter archives.",
+  "type": "object",
+  "properties": {
+    "schema": {
+      "type": "string",
+      "enum": ["sofia.model-manifest.v1"]
+    },
+    "name": {
+      "type": "string"
+    },
+    "publisher": {
+      "type": "string"
+    },
+    "license": {
+      "type": "string"
+    },
+    "source_repository": {
+      "type": "string",
+      "format": "uri"
+    },
+    "artifact_type": {
+      "type": "string",
+      "enum": ["scientific-edge-runtime", "neural-checkpoint", "linear-model"]
+    },
+    "version": {
+      "type": "string"
+    },
+    "checkpoint": {
+      "type": ["string", "null"]
+    },
+    "feature_schema": {
+      "type": ["string", "null"]
+    },
+    "parameters_sha256": {
+      "type": ["string", "null"],
+      "pattern": "^[a-fA-F0-9]{64}$"
+    },
+    "training": {
+      "type": "object",
+      "properties": {
+        "trained": { "type": "boolean" },
+        "dataset": { "type": ["string", "null"] },
+        "metrics": { "type": ["object", "null"] },
+        "note": { "type": "string" }
+      },
+      "required": ["trained"]
+    },
+    "provenance": {
+      "type": "object",
+      "properties": {
+        "git_commit": { "type": ["string", "null"] },
+        "release": { "type": ["string", "null"] },
+        "timestamp_utc": { "type": ["string", "null"] }
+      }
+    }
+  },
+  "required": ["schema", "name", "publisher", "license", "source_repository", "artifact_type", "version", "training"]
+}