File size: 8,489 Bytes
1eff9b2 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 | # ORTHO-32 Java SDK
Official JVM developer surface for ORTHO-32 β a deterministic, tensor-augmented ORTHO architecture.
> Java Application β ORTHO Java SDK β ORTHO Protocol / Native Bridge β ORTHO Host Service β Transport β ORTHO Fabric β Hardware
Applications program against stable, typed Java APIs (`OrthoDevice`, `FabricCommand`, `TensorJob`, `ExecutionTrace`, `TheoremResult`) and never touch PCIe BARs, DMA windows, or raw MMIO. The SDK hides transport internals; the same code runs against a simulator, FPGA, ASIC, PCIe, USB, or Ethernet device.
## What is ORTHO-32?
ORTHO-32 is a 32-bit ORTHO ISA with deterministic arbitration, a 4-cycle TMUL tensor unit, cycle-accurate tracing (H=0 determinism), and 12 mechanically-checked theorems (Lean4 + HOL Light). Fabric commands are logically addressed, epoch-ordered, and completed with architectural-cycle timestamps β not wall-clock time.
## What this SDK provides
- **Stable Java APIs** over ORTHO system contracts: `org.ortho32`, `org.ortho32.device`, `fabric`, `compute`, `tensor`, `trace`, `verify`, `security`, `agent`, `system`, `transport`, `exceptions`
- **Immutable value objects, records, `CompletableFuture` async, `Flow.Publisher` streaming, typed exceptions, `AutoCloseable` resources**
- **SimulatorTransport** β deterministic fake fabric for offline development, CI, and tests (no hardware required)
- **JSON Schemas** for `FabricCommand`, `FabricCompletion`, `ExecutionTrace`, `TheoremResult`, `Attestation`
- **Examples & integration tests** validated against `SimulatorTransport`
## Quick-start (5 lines)
Add the SDK to your Gradle project and run with the simulator (Java 21):
```kotlin
dependencies { implementation("dev.ortho32:ortho32-sdk:0.1.0") }
```
```java
try (OrthoRuntime runtime = OrthoRuntime.open();
OrthoSession session = runtime.openSession()) {
OrthoDevice device = session.devices().firstAvailable();
TensorJob job = TensorJob.builder()
.device(device)
.operation(TensorOperation.TMUL)
.inputA(matrixA)
.inputB(matrixB)
.build();
TensorResult result = session.tensor().submit(job).join();
System.out.println("cycles: " + result.cycles());
System.out.println("trace: " + result.traceHash());
}
```
No drivers, no hardware β `OrthoRuntime.open()` defaults to `SimulatorTransport` when no device is present. Swap to PCIe/USB/Ethernet by changing transport, not application code.
## Module overview
| Module | Artifact | Purpose |
|---|---|---|
| `ortho-core` | `org.ortho32` | `OrthoRuntime`, `OrthoSession`, `OrthoContext`, `OrthoVersion`, `OrthoResult` |
| `ortho-device` | `org.ortho32.device` | `OrthoDevice`, `OrthoDeviceId/Info/Capabilities/State` |
| `ortho-fabric` | `org.ortho32.fabric` | `FabricCommand`, `FabricCompletion`, `FabricAddress/Opcode/Epoch/Slot` |
| `ortho-compute` | `org.ortho32.compute` | Scalar compute submission |
| `ortho-tensor` | `org.ortho32.tensor` | `Tensor`, `TensorShape/Buffer/Job/Operation/Result`, `TensorLatency` |
| `ortho-trace` | `org.ortho32.trace` | `ExecutionTrace`, `CycleRecord`, `TraceHash`, `TraceComparator` |
| `ortho-verify` | `org.ortho32.verify` | `TheoremId`, `TheoremResult`, `VerificationStatus/Report`, `CrossVerificationResult` |
| `ortho-security` | `org.ortho32.security` | `Capability`, `Permission`, `SecurityContext`, `Attestation` |
| `ortho-agent` | `org.ortho32.agent` | `AgentIntent`, `AgentTask`, `AgentResult`, `AgentCapability` |
| `ortho-transport` | `org.ortho32.transport` | `OrthoTransport` (internal), `SimulatorTransport`, `NativeHostTransport`, `PCIe/USB/Ethernet` |
| `ortho-system` | `org.ortho32.system` | System utilities, versioning |
Per-module JARs + aggregate `ortho32-sdk.jar`, sources JAR, Javadoc JAR, Maven publication metadata, reproducible builds, checksums, dependency locking.
## Transport options
All transports expose the same `OrthoSession` API. Application code is transport-agnostic.
| Transport | Class | Use |
|---|---|---|
| **Simulator** | `SimulatorTransport` | Deterministic fake fabric, offline tests, CI. Required. No hardware. |
| **PCIe** | `PCIeTransport` | Native host service over PCIe BAR |
| **USB** | `USBTransport` | USB-attached ORTHO device |
| **Ethernet** | `EthernetTransport` | Remote ORTHO fabric over UDP/TCP |
| **Native** | `NativeHostTransport` | JNI bridge to ORTHO Host Service |
```java
// Explicit simulator (tests/examples)
OrthoRuntime runtime = OrthoRuntime.open(new SimulatorTransport());
// Production - auto-detect or inject via service loader
OrthoRuntime runtime = OrthoRuntime.open();
```
> Rule: `FabricCommand` is the logical API. Applications never write PCIe BAR registers.
## Versioning
Semantic versioning for public Java APIs. Compatibility is a tuple:
```
SDK-Version + Fabric-Protocol-Version + Device-ABI-Version
```
Access via `OrthoVersion`:
```java
OrthoVersion v = OrthoRuntime.open().version();
System.out.println(v.sdkVersion()); // e.g. 0.1.0
System.out.println(v.fabricProtocolVersion()); // e.g. 1
System.out.println(v.deviceABIVersion()); // e.g. 2
```
- **SDK version** β bumped on API change; follows SemVer
- **Fabric protocol version** β bumped on wire-format change
- **Device ABI version** β bumped on scratchpad / register map change
- `OrthoRuntime` checks compatibility on `openSession()` and fails fast on mismatch
See `CHANGELOG.md` for history.
## Build instructions
Requirements: Java 21 toolchain, Gradle 8.x
```bash
git clone https://github.com/ortho32/ortho32-sdk-java.git
cd ortho32-sdk-java
./gradlew build # all modules, tests with SimulatorTransport
./gradlew :integration-tests:test --info # integration tests only (no hardware)
./gradlew publishToMavenLocal # artifacts to ~/.m2
./gradlew javadoc # aggregated Javadoc
```
Reproducible builds, dependency locking (`gradle.lockfile`), checksums. Gradle Kotlin DSL.
## Examples
All examples run without hardware via `SimulatorTransport`.
| Example | Path | Description |
|---|---|---|
| device-list | `examples/device-list` | Enumerate and print available devices |
| tensor-run | `examples/tensor-run` | Build `TensorJob`, submit `TMUL`, print cycles & `traceHash` |
| trace-replay | `examples/trace-replay` | Capture trace, compute hash, replay, compare (H=0) |
| proof-verify | `examples/proof-verify` | Verify 12 theorems via `VerifyClient`, table with Lean/HOL columns |
| agent-client | `examples/agent-client` | Dispatch `AgentTask` via `AgentClient`, print result |
Run:
```bash
./gradlew :examples:device-list:run
./gradlew :examples:tensor-run:run
./gradlew :examples:trace-replay:run
./gradlew :examples:proof-verify:run
./gradlew :examples:agent-client:run
```
## API style
- Immutable value objects; `record` where appropriate
- No raw native pointers in public API
- No `Map<String,Object>` when schema exists
- Async via `CompletableFuture`, streaming via `Flow.Publisher`
- Typed exceptions (`OrthoException` hierarchy)
- `AutoCloseable` sessions and transports
## Contributing
1. Fork, create feature branch
2. `./gradlew build` β must pass with `SimulatorTransport` (no hardware)
3. Add schema + Javadoc for new public types
4. Update `CHANGELOG.md`
5. PR with determinism proof (`TraceHash` equality) where applicable
License: MIT. See `LICENSE`.
---
## Sovereign Boundary
This repository operates under the **SnapKitty Method**: public by default, sovereign by construction.
```
CODE β PUBLIC (this repository)
PROOF β PUBLIC (Lean 4 / formal verification artifacts)
SPEC β PUBLIC (interfaces, schemas, invariants)
HISTORY β PUBLIC (cryptographic provenance, WORM-sealed)
AUTHORITY β SOVEREIGN (Bel Esprit D'Accord Irrevocable Trust)
STATE β SOVEREIGN (credentials, private data, operational secrets)
EXECUTION β AUTHORIZED (requires sovereign state β not in this repo)
```
> **"Here is the machine. You do not own the state it operates on."**
Reading the source does not grant execution authority. Forking the repo does not grant deployment rights. The code is verifiable. The authority is not transferable.
**[β Full architecture: SOVEREIGN_METHOD.md](./SOVEREIGN_METHOD.md)**
**[β License terms: LICENSE](./LICENSE)** Β· **[β IP estate: NOTICE](./NOTICE)**
---
*Copyright (C) 2026 Bel Esprit D'Accord Irrevocable Trust (EIN 42-697643) Β· `Ξ© = TRUST β§ CODE`*
|