Snapkitty/ortho32-sdk-java

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):

dependencies { implementation("dev.ortho32:ortho32-sdk:0.1.0") }

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

// 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:

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

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:

./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

→ License terms: LICENSE · → IP estate: NOTICE

---

Copyright (C) 2026 Bel Esprit D'Accord Irrevocable Trust (EIN 42-697643) · Ω = TRUST ∧ CODE