README.md

# 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`*