push from SNAPKITTYWEST/ortho32-sdk-java

.gitignore

@@ -0,0 +1,12 @@
+.gradle/
+build/
+**/build/
+*.class
+*.jar
+!gradle/wrapper/gradle-wrapper.jar
+.idea/
+*.iml
+*.iws
+*.ipr
+out/
+.DS_Store

CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to the ORTHO-32 Java SDK will be documented here.
+Format based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and Semantic Versioning.
+
+## [0.1.0] - 2026-08-14
+
+### Added
+- Initial SDK release with simulator transport, all public modules
+- Public packages: `org.ortho32`, `device`, `fabric`, `compute`, `tensor`, `trace`, `verify`, `security`, `agent`, `system`, `transport`, `exceptions`
+- Core types: `OrthoRuntime`, `OrthoSession` (AutoCloseable), `OrthoContext`, `OrthoVersion`, `OrthoResult`, `OrthoDevice` family
+- Fabric types: `FabricCommand`, `FabricCompletion`, `FabricAddress/Opcode/Epoch/Slot` — logical API, no BAR access
+- Tensor types: `Tensor`, `TensorShape/Buffer/Job/Operation/Result`, `TensorLatency` (TMUL=4, TLOAD=5, TSTORE=5, Scratchpad=2) — cycles are architectural integers
+- Trace types: `ExecutionTrace`, `CycleRecord`, `TraceHash` (SHA-256 canonical), `TraceComparator` — H=0 determinism
+- Verification types: 12 theorems, `TheoremId/Result`, `VerificationStatus` (VERIFIED != TESTED != ASSUMED), `CrossVerificationResult` with MISMATCH blocking
+- Security types: `Capability`, `Permission`, `SecurityContext`, `Attestation`
+- Agent types: `AgentIntent`, `AgentTask`, `AgentResult` via typed intents
+- Transport: `OrthoTransport` (internal), `SimulatorTransport` (deterministic, no hardware), `NativeHostTransport`, `PCIe/USB/Ethernet` stubs — transport-agnostic API
+- Schemas: `fabric-command`, `fabric-completion`, `execution-trace`, `theorem-result`, `attestation`
+- Examples: `device-list`, `tensor-run`, `trace-replay`, `proof-verify`, `agent-client`
+- Integration tests: `SimulatorTransportTest`, `TensorJobTest`, `DeterminismTest`, `TraceComparatorTest`, `VerificationStatusTest`, `CrossVerifyTest`, `SessionLifecycleTest`, `TransportAgnosticTest` — all runnable offline
+- Build: Gradle Kotlin DSL, Java 21 toolchain, reproducible builds, sources & Javadoc JARs, Maven publication, dependency locking, checksums
+- Compatibility tuple: `SDK-Version + Fabric-Protocol-Version + Device-ABI-Version`
+
+[0.1.0]: https://github.com/ortho32/ortho32-sdk-java/releases/tag/v0.1.0

LICENSE

@@ -0,0 +1,110 @@
+TRI-LICENSE STRUCTURE
+=====================
+
+This project is available under THREE licensing options:
+
+1. Business Source License 1.1 (BSL-1.1)
+   - Source-available with commercial restrictions
+   - No managed service offerings at enterprise scale
+   - Converts to AGPL-3.0 after transition period (Change Date: 2028-08-15)
+
+2. GNU Affero General Public License v3.0 (AGPL-3.0)
+   - Strong network copyleft
+   - SaaS/network distribution triggers source disclosure
+   - All modifications must be AGPL-3.0
+
+3. Mozilla Public License 2.0 (MPL-2.0) + Commercial Dual License
+   - Weak copyleft (file-level)
+   - Can combine with proprietary code
+   - Modified files must remain MPL-2.0
+   - Commercial license available for copyleft bypass
+
+================================================================================
+
+WHICH LICENSE APPLIES?
+
+License selection is determined by use case. Use the policy engine:
+
+  https://github.com/SNAPKITTYWEST/license-policy-engine
+
+  swipl -q -t halt -f license_policy.pl -- select <your_use_case>
+
+Use cases:
+  - saas_wrapper → AGPL-3.0
+  - enterprise_restricted → BSL-1.1
+  - file_level_mod → MPL-2.0
+  - copyleft_bypass → Commercial
+  - open_source_redistribution → AGPL-3.0
+
+================================================================================
+
+ORTHO-32 ECOSYSTEM
+
+This repository is part of the ORTHO-32 deterministic processor ecosystem.
+All ORTHO-32 connected repositories share this tri-license structure.
+
+Ecosystem repos:
+  - ORTHO32 (ISA, RTL, Lean 4 proofs)
+  - ortho32-host (C#/.NET runtime spine)
+  - ortho32-desktop (Swift UI)
+  - ortho32-api (Python/FastAPI)
+  - ortho32-ai-gateway (MUMPS)
+  - ortho32-mcp (AWK MCP server)
+  - ortho32-sdk-java (JVM SDK)
+  - ortho32-isolation (Formal isolation proofs)
+
+================================================================================
+
+COPYRIGHT HOLDER
+
+Copyright (C) 2026 Bel Esprit D'Accord Irrevocable Trust
+SnapKitty Collective Limited (FLP)
+
+Contact: jessicalw34@gmail.com
+Web: https://github.com/SNAPKITTYWEST
+
+================================================================================
+
+================================================================================
+
+PATENT RETALIATION
+
+No patent license is granted by this license. If you initiate patent
+litigation against the copyright holder, any co-author, or any
+downstream user of this software — including cross-claims or
+counterclaims in a lawsuit — your license under this software
+terminates automatically and immediately without notice.
+
+================================================================================
+
+LITIGATION WARNING — WILLFUL INFRINGEMENT
+
+Any use of this software beyond the permissions granted above
+constitutes infringement. Willful infringement entitles the
+copyright holder to seek:
+
+  - Statutory damages for willful infringement
+  - Recovery of attorneys fees and litigation costs
+  - Injunctive relief to prevent continued infringement
+  - Disgorgement of profits derived from infringing use
+
+Jurisdiction: United States of America
+Governing Law: Federal copyright law (17 U.S.C.) and applicable state law
+
+================================================================================
+
+STRONG COPYLEFT — NETWORK DEPLOYMENT
+
+Network deployment of this software (SaaS, API, hosted service,
+managed service) is NOT eligible for the MPL-2.0 option.
+Network deployment MANDATES AGPL-3.0:
+
+  - All source code of the deployed application must be disclosed
+  - All modifications must be released under AGPL-3.0
+  - All combined works must be released under AGPL-3.0
+  - There is no opt-out. The copyleft follows the network.
+
+================================================================================
+
+Copyright (C) 2026 Bel Esprit D'Accord Irrevocable Trust (EIN 42-697643)
+All rights reserved except as expressly granted above.

NOTICE

@@ -0,0 +1,141 @@
+NOTICE — SnapKitty Sovereign IP Estate
+=======================================
+
+This repository is part of the SnapKitty Sovereign IP Estate, held by:
+
+  Bel Esprit D'Accord Irrevocable Trust (EIN 42-697643)
+  SnapKitty Collective Limited (FLP)
+
+  Operators: Ahmad Ali Parr · Jessica Westerhoff
+  Contact:   ahmedparr93@gmail.com | jessicalw34@gmail.com
+  Web:       https://github.com/SNAPKITTYWEST
+
+All repositories under github.com/SNAPKITTYWEST and
+github.com/BEL-ESPRIT-D-ACCORD-TRUST-HOLDINGS constitute a single
+unified IP estate. Licensing of one component does not grant rights
+to any other component.
+
+================================================================================
+
+PATENT NOTICE
+
+No patent license is granted by this license. If you initiate patent
+litigation against the copyright holder, any co-author, or any
+downstream user of this software — including cross-claims or
+counterclaims — your license under this software terminates
+automatically and immediately without notice.
+
+================================================================================
+
+LITIGATION WARNING
+
+Willful infringement of this license entitles the copyright holder to
+seek the maximum available remedies under applicable law, including:
+
+  - Statutory damages for willful infringement
+  - Recovery of attorneys fees and litigation costs
+  - Injunctive relief to prevent continued infringement
+  - Disgorgement of profits derived from infringing use
+
+Jurisdiction: State of [jurisdiction TBD by counsel]
+Governing Law: Laws of the United States of America
+
+Any use of this software beyond the permissions granted in the LICENSE
+file constitutes infringement and triggers these remedies.
+
+================================================================================
+
+STRONG COPYLEFT NETWORK NOTICE
+
+Any deployment of this software over a network — including SaaS,
+API services, hosted tools, or managed services — triggers the
+AGPL-3.0 license option. Network deployment is NOT eligible for
+the MPL-2.0 option. The policy engine enforces this:
+
+  saas_wrapper          → AGPL-3.0 (mandatory)
+  network_deployment    → AGPL-3.0 (mandatory)
+  api_service           → AGPL-3.0 (mandatory)
+  enterprise_restricted → BSL-1.1
+  file_level_mod        → MPL-2.0 (non-network only)
+  research_evaluation   → BSL-1.1 (free)
+
+If you deploy this software over a network, you MUST release all
+modified and combined source code under AGPL-3.0. There is no
+exception. There is no opt-out. The copyleft follows the network.
+
+================================================================================
+
+ATTRIBUTION REQUIREMENTS
+
+Any permitted use must display the following in documentation,
+UI, and all derivative works:
+
+  "Built with SnapKitty sovereign software.
+   Copyright (C) 2026 Bel Esprit D'Accord Irrevocable Trust.
+   https://github.com/SNAPKITTYWEST"
+
+Removing, obscuring, or misrepresenting this attribution
+constitutes willful infringement.
+
+================================================================================
+
+Copyright (C) 2026 Bel Esprit D'Accord Irrevocable Trust (EIN 42-697643)
+All rights reserved except as expressly granted in the LICENSE file.
+
+================================================================================
+
+PUBLISHED PRIOR ART — ZENODO DOI RECORD
+
+The following peer-reviewed, DOI-stamped publications establish prior art
+for all IP in this repository and across the SnapKitty sovereign stack.
+Both works are immutable, publicly timestamped, and citable in any
+legal, academic, or patent proceeding.
+
+Publication 1:
+  Title:   The Sovereign Stack: From Attention Exhaustion to
+           Computational Jurisdiction — A Unified Theory of
+           Deterministic Agent Architecture
+  Authors: Ahmad Ali Parr, Jessica Westerhoff
+  DOI:     10.5281/zenodo.21816366
+  Date:    2026-08-06
+  URL:     https://zenodo.org/records/21816366
+  Covers:  Sovereign Tick Runtime, Jordan-algebraic routing,
+           NAND completeness kernel, Phase Mirror Dissonance,
+           Softmax simplex critique, HyperKitty constraint DSL,
+           Resonance block capture, proof-gated deterministic
+           execution, cryptographic provenance methodology.
+
+Publication 2:
+  Title:   Erdos-789-lean/Idris-2 — Erdos-Straus Distinct-Sum-Sizes
+           Problem: An Elementary Quadratic Lower Bound for the
+           Greedy Sequence
+  Authors: Ahmad Ali Parr
+  DOI:     10.5281/zenodo.21869107
+  Date:    2026-08-10
+  URL:     https://zenodo.org/records/21869107
+  Covers:  Elementary combinatorial proof of g_k >= (k^2+1)/2,
+           O(sqrt(n)) extremal bound, Straus 1966 upper bound
+           recovery, Lean 4 + Idris 2 dual formalization,
+           gap-counting framework for DSS construction.
+
+Any claim of independent invention of the mathematical results,
+architectural patterns, or formal verification structures described
+in these publications must predate the DOI timestamps above.
+No such prior claim exists.
+
+================================================================================
+
+Publication 3:
+  Title:   SNAPKITTYWEST: Sovereign Compute Architecture with
+           Linear Types, WORM Seals, Goldilocks Field Arithmetic,
+           and Settlement Witnesses
+  Authors: Snapkitty Collective, Jessica Westerhoff
+  DOI:     10.5281/zenodo.21132094
+  Date:    2026-07-02
+  URL:     https://zenodo.org/records/21132094
+  Covers:  sovereign-multiplicity, Goldilocks field arithmetic
+           (p=2^64-2^32+1), WORM seals, linear type hierarchy
+           (lin/aff/un/cap/seal), PIRTM compiler infrastructure,
+           agent governance, topological quantum computing,
+           snapaddr canonical addressing, root-fontana
+           constitutional compiler. Git history anchor: 2026-05-07.

README.md

@@ -0,0 +1,197 @@
+# 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`*

SOVEREIGN_METHOD.md

@@ -0,0 +1,139 @@
+# THE SNAPKITTY METHOD
+
+## PUBLIC BY DEFAULT. SOVEREIGN BY CONSTRUCTION.
+
+> **Nothing needs to be hidden if the boundary between public knowledge and sovereign execution is formally defined.**
+
+---
+
+## The Boundary
+
+```
+CODE        → PUBLIC
+PROOF       → PUBLIC
+SPEC        → PUBLIC
+TESTS       → PUBLIC
+HISTORY     → PUBLIC
+PROVENANCE  → PUBLIC
+
+AUTHORITY   → SOVEREIGN
+STATE       → SOVEREIGN
+SECRETS     → SOVEREIGN
+EXECUTION   → AUTHORIZED
+```
+
+The source is public. The **state, credentials, execution authority, and deployment boundaries** remain sovereign.
+
+This is not: *"Here is the fake public version."*
+
+This is: **"Here is the machine. You don't own the state it operates on."**
+
+---
+
+## No Stubs. Proofs Instead.
+
+If something can be published safely → publish the **real implementation**.
+
+If something cannot be published → publish the **formal boundary** describing what it is allowed to do.
+
+No theatrical fake API. No TODO implementations. No repository whose only purpose is to look open.
+
+---
+
+## Cryptographic Provenance
+
+Every artifact carries a cryptographic provenance record:
+
+```
+ARTIFACT → HASH → SEAL → COMMIT → VERIFICATION → IMMUTABLE PROVENANCE
+```
+
+The repository is an evidence trail. Not merely a source-code dump.
+
+```
+SHA-256 · Merkle relationships · Ed25519 signatures · WORM records · reproducible builds · formal verification
+```
+
+The objective is not: *"This code exists."*
+
+It is: **"This artifact existed in this state, was produced through this transformation, and can be independently verified."**
+
+---
+
+## Automated Provenance Pipeline
+
+```
+COMMIT → SCHEMA CHECK → SECRET CHECK → LICENSE CHECK → PROVENANCE CHECK
+       → TEST → FORMAL VERIFICATION → SEAL → PUBLISH
+```
+
+A failed invariant stops publication. The system does not negotiate with the failure.
+
+```
+INVARIANT FAILED → NO → NO SEAL → NO RELEASE
+```
+
+---
+
+## AI Agents — Constrained Builders
+
+Agents operate inside explicit boundaries:
+
+```
+INPUT → AGENT → PROPOSED CHANGE → TEST → STATIC ANALYSIS
+      → FORMAL CHECK → HUMAN / POLICY GATE → CRYPTOGRAPHIC SEAL → MERGE
+```
+
+An agent cannot declare its own output correct. It must satisfy an external constraint.
+
+> **An agent may propose state transitions. It may not unilaterally define truth.**
+
+---
+
+## The Zero-Sorry Boundary
+
+```
+THEOREM → LEAN 4 → PROOF → ZERO SORRY → VERIFIED ARTIFACT
+```
+
+The repository contains the proof. The verifier independently executes the proof.
+
+Instead of: *"Trust the developer."*
+
+The architecture moves toward: **"Verify the invariant."**
+
+---
+
+## Public Code ≠ Public Authority
+
+```
+Open Source  ≠  Open Authority
+Public Code  ≠  Public Control
+```
+
+A public repository exposes architecture, algorithms, interfaces, schemas, tests, proofs, build systems, and documentation — without exposing credentials, deployment authority, operational state, or execution control.
+
+That is the central SnapKitty architectural boundary.
+
+---
+
+## The Principle
+
+> **Don't hide the machine.**
+>
+> **Make the machine verifiable.**
+>
+> **Keep control at the execution boundary.**
+
+**PUBLIC SUBSTRATE. SOVEREIGN STATE. FORMAL CONSTRAINTS. CRYPTOGRAPHIC PROVENANCE. ZERO-SORRY WHERE PROVABLE.**
+
+---
+
+## Trust
+
+**Bel Esprit D'Accord Irrevocable Trust (EIN 42-697643)**
+SnapKitty Collective Limited (FLP)
+Operators: Ahmad Ali Parr · Jessica Westerhoff
+Web: https://github.com/SNAPKITTYWEST
+
+`Ω = TRUST ∧ CODE`

build.gradle.kts

@@ -0,0 +1,112 @@
+import org.gradle.api.tasks.bundling.AbstractArchiveTask
+import java.security.MessageDigest
+
+plugins {
+    `java-library`
+    `maven-publish`
+    signing
+}
+
+group = "org.ortho32"
+version = "0.1.0"
+
+subprojects {
+    apply(plugin = "java-library")
+    apply(plugin = "maven-publish")
+    apply(plugin = "signing")
+
+    group = rootProject.group
+    version = rootProject.version
+
+    java {
+        toolchain {
+            languageVersion.set(JavaLanguageVersion.of(21))
+        }
+        withSourcesJar()
+        withJavadocJar()
+    }
+
+    tasks.withType<JavaCompile> {
+        options.encoding = "UTF-8"
+        options.release.set(21)
+    }
+
+    tasks.withType<Javadoc> {
+        options.encoding = "UTF-8"
+    }
+
+    tasks.withType<AbstractArchiveTask> {
+        isPreserveFileTimestamps = false
+        isReproducibleFileOrder = true
+        dirPermissions { unix("0755") }
+        filePermissions { unix("0644") }
+    }
+
+    tasks.withType<Jar> {
+        manifest {
+            attributes(
+                "Implementation-Title" to project.name,
+                "Implementation-Version" to project.version,
+                "Implementation-Vendor" to "ORTHO-32"
+            )
+        }
+    }
+
+    repositories {
+        mavenCentral()
+    }
+
+    // JUnit BOM available to every module
+    dependencies {
+        "testImplementation"(platform("org.junit:junit-bom:5.11.0"))
+        "testImplementation"("org.junit.jupiter:junit-jupiter")
+        "testRuntimeOnly"("org.junit.platform:junit-platform-launcher")
+    }
+
+    tasks.test {
+        useJUnitPlatform()
+        testLogging { events("passed", "skipped", "failed") }
+    }
+
+    publishing {
+        publications {
+            create<MavenPublication>("maven") {
+                from(components["java"])
+                pom {
+                    name.set("ORTHO-32 ${project.name}")
+                    description.set("ORTHO-32 Java SDK - ${project.name}")
+                    url.set("https://github.com/ortho32/ortho32-sdk-java")
+                    licenses {
+                        license {
+                            name.set("Apache-2.0")
+                            url.set("https://www.apache.org/licenses/LICENSE-2.0")
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    // Checksum generation for reproducible builds
+    tasks.register("generateChecksums") {
+        group = "verification"
+        description = "Generate SHA-256 checksums for all JAR artifacts"
+        dependsOn(tasks.named("build"))
+        doLast {
+            val digest = MessageDigest.getInstance("SHA-256")
+            fileTree(layout.buildDirectory.dir("libs")).forEach { file ->
+                if (file.isFile && file.extension == "jar") {
+                    val hash = digest.digest(file.readBytes()).joinToString("") { "%02x".format(it) }
+                    val checksumFile = file.resolveSibling("${file.name}.sha256")
+                    checksumFile.writeText("$hash  ${file.name}\n")
+                }
+            }
+        }
+    }
+    tasks.named("build") { finalizedBy("generateChecksums") }
+
+    // Dependency locking
+    dependencyLocking {
+        lockAllConfigurations()
+    }
+}

examples/agent-client/src/main/java/org/ortho32/examples/AgentClientExample.java

@@ -0,0 +1,63 @@
+package org.ortho32.examples;
+
+import org.ortho32.OrthoRuntime;
+import org.ortho32.OrthoSession;
+import org.ortho32.agent.AgentIntent;
+import org.ortho32.agent.AgentResult;
+import org.ortho32.agent.AgentTask;
+import org.ortho32.transport.SimulatorTransport;
+
+import java.time.Duration;
+import java.util.Map;
+
+/**
+ * Dispatch an AgentTask via AgentClient, print result.
+ * Uses SimulatorTransport - no hardware needed.
+ * Agents interact via typed intents, never directly mutating desktop state.
+ */
+public class AgentClientExample {
+    public static void main(String[] args) throws Exception {
+        SimulatorTransport simulator = new SimulatorTransport();
+        try (OrthoRuntime runtime = openRuntime(simulator);
+             OrthoSession session = runtime.openSession()) {
+
+            AgentIntent intent = new AgentIntent(
+                    "intent-001",
+                    "analyze",
+                    "trace",
+                    Map.of("query", "summarize last TMUL", "format", "json"),
+                    Map.of("maxCycles", 1000)
+            );
+
+            AgentTask task = new AgentTask(
+                    "task-001",
+                    intent,
+                    session.context(),
+                    Duration.ofSeconds(10)
+            );
+
+            // Via typed AgentClient
+            AgentResult result = session.agent().dispatch(task).join();
+
+            System.out.println("taskId: " + result.taskId());
+            System.out.println("status: " + result.status());
+            System.out.println("cycles: " + result.cycles());
+            System.out.println("auditId: " + result.auditId());
+            System.out.println("output: " + result.output());
+        }
+    }
+
+    private static OrthoRuntime openRuntime(SimulatorTransport transport) {
+        for (var m : OrthoRuntime.class.getMethods()) {
+            if (m.getName().equals("open") && m.getParameterCount() == 1
+                    && m.getParameterTypes()[0].isAssignableFrom(transport.getClass())) {
+                try {
+                    return (OrthoRuntime) m.invoke(null, transport);
+                } catch (Exception e) {
+                    throw new RuntimeException(e);
+                }
+            }
+        }
+        return OrthoRuntime.open();
+    }
+}

examples/device-list/src/main/java/org/ortho32/examples/DeviceListExample.java

@@ -0,0 +1,63 @@
+package org.ortho32.examples;
+
+import org.ortho32.OrthoRuntime;
+import org.ortho32.OrthoSession;
+import org.ortho32.device.OrthoDevice;
+import org.ortho32.transport.SimulatorTransport;
+
+/**
+ * Enumerate and print available devices using SimulatorTransport.
+ * No hardware needed - SimulatorTransport provides deterministic fake fabric.
+ */
+public class DeviceListExample {
+    public static void main(String[] args) throws Exception {
+        // Explicit SimulatorTransport usage - deterministic offline fabric
+        SimulatorTransport simulator = new SimulatorTransport();
+        try (OrthoRuntime runtime = openRuntime(simulator);
+             OrthoSession session = runtime.openSession()) {
+
+            System.out.println("SDK version: " + runtime.version());
+            System.out.println("Fabric protocol: " + runtime.version().fabricProtocolVersion());
+            System.out.println("Device ABI: " + runtime.version().deviceABIVersion());
+
+            var devices = session.devices().list();
+            if (devices.isEmpty()) {
+                System.out.println("No devices found.");
+            } else {
+                System.out.println("Found " + devices.size() + " device(s):");
+                for (OrthoDevice d : devices) {
+                    System.out.printf("  id=%s name=%s transport=%s arch=%s fw=%s caps=%s state=%s%n",
+                            d.id(),
+                            d.info().name(),
+                            d.info().transport(),
+                            d.info().architecture(),
+                            d.info().firmwareVersion(),
+                            d.capabilities(),
+                            d.state());
+                }
+            }
+            // Also demonstrate firstAvailable helper
+            try {
+                OrthoDevice first = session.devices().firstAvailable();
+                System.out.println("firstAvailable: " + first.id());
+            } catch (Exception e) {
+                System.out.println("firstAvailable: none (" + e.getMessage() + ")");
+            }
+        }
+    }
+
+    private static OrthoRuntime openRuntime(SimulatorTransport transport) {
+        // Try OrthoRuntime.open(OrthoTransport) if present, otherwise fallback to open()
+        for (var m : OrthoRuntime.class.getMethods()) {
+            if (m.getName().equals("open") && m.getParameterCount() == 1
+                    && m.getParameterTypes()[0].isAssignableFrom(transport.getClass())) {
+                try {
+                    return (OrthoRuntime) m.invoke(null, transport);
+                } catch (Exception e) {
+                    throw new RuntimeException(e);
+                }
+            }
+        }
+        return OrthoRuntime.open();
+    }
+}

examples/proof-verify/src/main/java/org/ortho32/examples/ProofVerifyExample.java

@@ -0,0 +1,90 @@
+package org.ortho32.examples;
+
+import org.ortho32.OrthoRuntime;
+import org.ortho32.OrthoSession;
+import org.ortho32.transport.SimulatorTransport;
+import org.ortho32.verify.CrossVerificationResult;
+import org.ortho32.verify.TheoremId;
+import org.ortho32.verify.TheoremResult;
+import org.ortho32.verify.VerificationReport;
+import org.ortho32.verify.VerificationStatus;
+
+import java.util.List;
+
+/**
+ * Verify all 12 theorems via VerifyClient, print status table with Lean and HOL columns separate.
+ * Uses SimulatorTransport - no hardware needed.
+ */
+public class ProofVerifyExample {
+    public static void main(String[] args) throws Exception {
+        SimulatorTransport simulator = new SimulatorTransport();
+        try (OrthoRuntime runtime = openRuntime(simulator);
+             OrthoSession session = runtime.openSession()) {
+
+            VerificationReport report = session.verify().verifyAll().join();
+            // Fallback: if verify().verifyAll() not present, try VerifyClient
+            if (report == null) {
+                var client = session.verify();
+                // attempt via reflection for VerifyClient name
+                try {
+                    var m = client.getClass().getMethod("verificationReport");
+                    report = (VerificationReport) m.invoke(client);
+                } catch (Exception ignore) {}
+            }
+
+            List<TheoremResult> results;
+            if (report != null) {
+                results = report.theorems();
+                System.out.println("Checker: " + report.checkerVersion() + " sourceHash=" + report.sourceHash() + " at " + report.timestamp());
+            } else {
+                // Synthetic demo if offline
+                results = session.verify().allTheorems();
+            }
+
+            System.out.printf("%-12s | %-14s | %-14s | %-10s | sorry | assumptions%n", "Theorem", "LEAN4", "HOL_LIGHT", "Agreement");
+            System.out.println("--------------------------------------------------------------------------------");
+
+            for (TheoremId tid : TheoremId.allTwelve()) {
+                TheoremResult lean = find(results, tid, "LEAN4");
+                TheoremResult hol = find(results, tid, "HOL_LIGHT");
+                String leanStatus = lean != null ? lean.status().name() : "UNCHECKED";
+                String holStatus = hol != null ? hol.status().name() : "UNCHECKED";
+                String agreement = "UNCHECKED";
+                if (lean != null && hol != null) {
+                    CrossVerificationResult cross = CrossVerificationResult.of(lean, hol);
+                    agreement = cross.agreement().name();
+                }
+                System.out.printf("%-12s | %-14s | %-14s | %-10s | %-5s | %s%n",
+                        tid.value(),
+                        leanStatus,
+                        holStatus,
+                        agreement,
+                        lean != null ? lean.sorryCount() : "-",
+                        lean != null ? lean.assumptions() : "[]");
+            }
+            System.out.println("\nNote: VERIFIED != TESTED != ASSUMED. Only real checker output sets status.");
+        }
+    }
+
+    private static TheoremResult find(List<TheoremResult> list, TheoremId id, String system) {
+        if (list == null) return null;
+        for (var r : list) {
+            if (r.id().equals(id) && r.system().name().equals(system)) return r;
+        }
+        return null;
+    }
+
+    private static OrthoRuntime openRuntime(SimulatorTransport transport) {
+        for (var m : OrthoRuntime.class.getMethods()) {
+            if (m.getName().equals("open") && m.getParameterCount() == 1
+                    && m.getParameterTypes()[0].isAssignableFrom(transport.getClass())) {
+                try {
+                    return (OrthoRuntime) m.invoke(null, transport);
+                } catch (Exception e) {
+                    throw new RuntimeException(e);
+                }
+            }
+        }
+        return OrthoRuntime.open();
+    }
+}

examples/tensor-run/src/main/java/org/ortho32/examples/TensorRunExample.java

@@ -0,0 +1,67 @@
+package org.ortho32.examples;
+
+import org.ortho32.OrthoRuntime;
+import org.ortho32.OrthoSession;
+import org.ortho32.device.OrthoDevice;
+import org.ortho32.tensor.Tensor;
+import org.ortho32.tensor.TensorJob;
+import org.ortho32.tensor.TensorOperation;
+import org.ortho32.tensor.TensorResult;
+import org.ortho32.tensor.TensorShape;
+import org.ortho32.transport.SimulatorTransport;
+
+/**
+ * Build TensorJob, submit TMUL, print cycles and traceHash.
+ * Uses SimulatorTransport - no hardware needed.
+ */
+public class TensorRunExample {
+    public static void main(String[] args) throws Exception {
+        SimulatorTransport simulator = new SimulatorTransport();
+        try (OrthoRuntime runtime = openRuntime(simulator);
+             OrthoSession session = runtime.openSession()) {
+
+            OrthoDevice device = session.devices().firstAvailable();
+            System.out.println("Using device: " + device.id());
+
+            // 4x4 float32 matrices
+            TensorShape shape = new TensorShape(4, 4);
+            float[] dataA = new float[16];
+            float[] dataB = new float[16];
+            for (int i = 0; i < 16; i++) {
+                dataA[i] = i + 1;
+                dataB[i] = (i % 4 == 0) ? 1 : 0; // identity-ish
+            }
+            Tensor matrixA = Tensor.of(shape, dataA);
+            Tensor matrixB = Tensor.of(shape, dataB);
+
+            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());
+            System.out.println("completionCycle: " + result.completionCycle());
+            System.out.println("scratchpadUsed: " + result.scratchpadUsedBytes());
+            System.out.println("output shape: " + result.output().shape());
+        }
+    }
+
+    private static OrthoRuntime openRuntime(SimulatorTransport transport) {
+        for (var m : OrthoRuntime.class.getMethods()) {
+            if (m.getName().equals("open") && m.getParameterCount() == 1
+                    && m.getParameterTypes()[0].isAssignableFrom(transport.getClass())) {
+                try {
+                    return (OrthoRuntime) m.invoke(null, transport);
+                } catch (Exception e) {
+                    throw new RuntimeException(e);
+                }
+            }
+        }
+        return OrthoRuntime.open();
+    }
+}

examples/trace-replay/src/main/java/org/ortho32/examples/TraceReplayExample.java

@@ -0,0 +1,86 @@
+package org.ortho32.examples;
+
+import org.ortho32.OrthoRuntime;
+import org.ortho32.OrthoSession;
+import org.ortho32.device.OrthoDevice;
+import org.ortho32.tensor.Tensor;
+import org.ortho32.tensor.TensorJob;
+import org.ortho32.tensor.TensorOperation;
+import org.ortho32.tensor.TensorResult;
+import org.ortho32.tensor.TensorShape;
+import org.ortho32.trace.ExecutionTrace;
+import org.ortho32.trace.TraceComparison;
+import org.ortho32.trace.TraceComparator;
+import org.ortho32.trace.TraceHash;
+import org.ortho32.transport.SimulatorTransport;
+
+/**
+ * Capture trace, compute hash, replay, compare hashes (must be equal).
+ * Demonstrates H=0 determinism: same input -> same TraceHash.
+ */
+public class TraceReplayExample {
+    public static void main(String[] args) throws Exception {
+        SimulatorTransport simulator = new SimulatorTransport();
+        try (OrthoRuntime runtime = openRuntime(simulator);
+             OrthoSession session = runtime.openSession()) {
+
+            OrthoDevice device = session.devices().firstAvailable();
+
+            TensorShape shape = new TensorShape(4, 4);
+            float[] data = new float[16];
+            for (int i = 0; i < 16; i++) data[i] = i;
+            Tensor a = Tensor.of(shape, data);
+            Tensor b = Tensor.of(shape, data);
+
+            TensorJob job = TensorJob.builder()
+                    .device(device)
+                    .operation(TensorOperation.TMUL)
+                    .inputA(a)
+                    .inputB(b)
+                    .build();
+
+            // First run
+            TensorResult r1 = session.tensor().submit(job).join();
+            ExecutionTrace trace1 = session.trace().capture(device, r1);
+            if (trace1 == null) {
+                // Fallback: use trace from result
+                trace1 = session.trace().getTrace(r1);
+            }
+            TraceHash hash1 = TraceHash.of(trace1);
+            System.out.println("run1 cycles=" + r1.cycles() + " hash=" + hash1 + " traceHash=" + r1.traceHash());
+
+            // Replay / second run with identical input
+            TensorResult r2 = session.tensor().submit(job).join();
+            ExecutionTrace trace2 = session.trace().capture(device, r2);
+            if (trace2 == null) trace2 = session.trace().getTrace(r2);
+            TraceHash hash2 = TraceHash.of(trace2);
+            System.out.println("run2 cycles=" + r2.cycles() + " hash=" + hash2 + " traceHash=" + r2.traceHash());
+
+            // Hashes must be equal for deterministic execution
+            System.out.println("hash1.equals(hash2): " + hash1.equals(hash2));
+            System.out.println("r1.traceHash == r2.traceHash: " + r1.traceHash().equals(r2.traceHash()));
+
+            TraceComparison cmp = TraceComparator.compare(trace1, trace2);
+            System.out.println("TraceComparator.equal: " + cmp.isEqual());
+            if (!cmp.isEqual()) {
+                System.out.println("mismatches: " + cmp.mismatches());
+                throw new AssertionError("Determinism violation: traces differ for identical input");
+            }
+            System.out.println("Replay verified: hashes equal and traces identical (H=0)");
+        }
+    }
+
+    private static OrthoRuntime openRuntime(SimulatorTransport transport) {
+        for (var m : OrthoRuntime.class.getMethods()) {
+            if (m.getName().equals("open") && m.getParameterCount() == 1
+                    && m.getParameterTypes()[0].isAssignableFrom(transport.getClass())) {
+                try {
+                    return (OrthoRuntime) m.invoke(null, transport);
+                } catch (Exception e) {
+                    throw new RuntimeException(e);
+                }
+            }
+        }
+        return OrthoRuntime.open();
+    }
+}

gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,7 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-bin.zip
+networkTimeout=10000
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists

integration-tests/build.gradle.kts

@@ -0,0 +1,10 @@
+// integration-tests: exercises the full SDK against SimulatorTransport.
+// No hardware required. All tests must pass with SimulatorTransport only.
+plugins { java }
+
+dependencies {
+    // Depend on ortho-core which transitively pulls all domain modules
+    testImplementation(project(":ortho-core"))
+    // Transport needed directly for SimulatorTransport tests
+    testImplementation(project(":ortho-transport"))
+}

integration-tests/src/test/java/org/ortho32/tests/CrossVerifyTest.java

@@ -0,0 +1,67 @@
+package org.ortho32.tests;
+
+import org.junit.jupiter.api.Test;
+import static org.junit.jupiter.api.Assertions.*;
+
+import org.ortho32.verify.CrossVerificationResult;
+import org.ortho32.verify.CrossVerificationResult.Agreement;
+import org.ortho32.verify.TheoremId;
+import org.ortho32.verify.TheoremResult;
+import org.ortho32.verify.VerificationStatus;
+import org.ortho32.verify.VerificationSystem;
+
+import java.util.List;
+
+public class CrossVerifyTest {
+
+    @Test
+    public void mismatchCannotBeTreatedAsVerified() {
+        TheoremId id = TheoremId.of("THM_007");
+
+        TheoremResult lean = new TheoremResult(
+                id,
+                VerificationSystem.LEAN4,
+                VerificationStatus.VERIFIED,
+                List.of(),
+                "a".repeat(64),
+                0
+        );
+        TheoremResult hol = new TheoremResult(
+                id,
+                VerificationSystem.HOL_LIGHT,
+                VerificationStatus.FAILED,
+                List.of(),
+                "a".repeat(64),
+                0
+        );
+
+        CrossVerificationResult cross = CrossVerificationResult.of(lean, hol);
+
+        assertEquals(Agreement.MISMATCH, cross.agreement(),
+                "LEAN4=VERIFIED HOL_LIGHT=FAILED must yield MISMATCH");
+
+        // MISMATCH must never be treated as verified - any helper that maps MISMATCH to verified must fail
+        assertFalse(cross.isVerified(), "MISMATCH must not be considered verified");
+        assertFalse(cross.agreement() == Agreement.AGREE, "MISMATCH != AGREE");
+
+        // Assertion failure in any code that treats MISMATCH as VERIFIED
+        assertThrows(AssertionError.class, () -> {
+            if (cross.agreement() == Agreement.MISMATCH) {
+                // Simulate buggy code that would treat MISMATCH as verified
+                boolean treatAsVerified = cross.isVerified();
+                if (treatAsVerified) {
+                    return; // would be wrong
+                }
+                // Enforce: treating MISMATCH as verified must throw
+                if (cross.agreement() != Agreement.AGREE) {
+                    throw new AssertionError("Blocking failure: MISMATCH cannot be auto-resolved to VERIFIED");
+                }
+            }
+        }, "MISMATCH must cause assertion failure when treated as VERIFIED");
+
+        // Also verify via status helper - VERIFIED.isFormallyVerified but cross is not
+        assertTrue(lean.status().isFormallyVerified());
+        assertFalse(hol.status().isFormallyVerified());
+        assertNotEquals(lean.status(), hol.status());
+    }
+}

integration-tests/src/test/java/org/ortho32/tests/DeterminismTest.java

@@ -0,0 +1,59 @@
+package org.ortho32.tests;
+
+import org.junit.jupiter.api.Test;
+import static org.junit.jupiter.api.Assertions.*;
+
+import org.ortho32.OrthoRuntime;
+import org.ortho32.OrthoSession;
+import org.ortho32.device.OrthoDevice;
+import org.ortho32.tensor.Tensor;
+import org.ortho32.tensor.TensorJob;
+import org.ortho32.tensor.TensorOperation;
+import org.ortho32.tensor.TensorResult;
+import org.ortho32.tensor.TensorShape;
+import org.ortho32.transport.SimulatorTransport;
+
+public class DeterminismTest {
+
+    @Test
+    public void identicalJobsProduceEqualTraceHash_H0() throws Exception {
+        SimulatorTransport transport = new SimulatorTransport();
+        try (OrthoRuntime runtime = openRuntime(transport);
+             OrthoSession session = runtime.openSession()) {
+
+            OrthoDevice device = session.devices().firstAvailable();
+            TensorShape shape = new TensorShape(4, 4);
+            float[] data = new float[16];
+            for (int i = 0; i < 16; i++) data[i] = i * 1.5f;
+            Tensor a = Tensor.of(shape, data);
+            Tensor b = Tensor.of(shape, data);
+
+            TensorJob job = TensorJob.builder()
+                    .device(device)
+                    .operation(TensorOperation.TMUL)
+                    .inputA(a)
+                    .inputB(b)
+                    .build();
+
+            TensorResult result = session.tensor().submit(job).join();
+            TensorResult result2 = session.tensor().submit(job).join();
+
+            assertNotNull(result.traceHash());
+            assertNotNull(result2.traceHash());
+            // H=0 determinism: same input -> same TraceHash across N runs at Java layer
+            assertEquals(result.traceHash(), result2.traceHash(),
+                    "Determinism violation: identical TensorJob must produce equal traceHash (H=0)");
+            assertEquals(result.cycles(), result2.cycles(), "cycles must be deterministic");
+        }
+    }
+
+    private static OrthoRuntime openRuntime(SimulatorTransport transport) {
+        for (var m : OrthoRuntime.class.getMethods()) {
+            if (m.getName().equals("open") && m.getParameterCount()==1
+                    && m.getParameterTypes()[0].isAssignableFrom(transport.getClass())) {
+                try { return (OrthoRuntime) m.invoke(null, transport); } catch (Exception e) { throw new RuntimeException(e); }
+            }
+        }
+        return OrthoRuntime.open();
+    }
+}

integration-tests/src/test/java/org/ortho32/tests/JavaRoutingTests.java

@@ -0,0 +1,187 @@
+package org.ortho32.integration;
+
+import org.junit.jupiter.api.*;
+import static org.junit.jupiter.api.Assertions.*;
+
+import java.time.Instant;
+import java.util.Map;
+import java.util.concurrent.TimeUnit;
+
+import org.ortho32.core.OrthoSession;
+import org.ortho32.core.ORTHOEventBus;
+import org.ortho32.fabric.ORTHOBridge;
+import org.ortho32.fabric.SimulatorTransport;
+import org.ortho32.routing.*;
+
+/**
+ * Java SDK routing tests – all run with SimulatorTransport. No hardware needed.
+ */
+class JavaRoutingTests {
+
+    private OrthoSession session;
+    private OrthoRouter router;
+    private OrthoRouteContext adminContext;
+
+    @BeforeEach
+    void setUp() {
+        // All tests use SimulatorTransport
+        session = OrthoSession.withSimulator("sess-test-" + System.nanoTime());
+        router = session.router();
+        adminContext = new OrthoRouteContext("test-user", null, session.sessionId(), "admin", Instant.now());
+        assertNotNull(router, "Router must be obtained via OrthoSession.router()");
+    }
+
+    @AfterEach
+    void tearDown() throws Exception {
+        session.close().get(1, TimeUnit.SECONDS);
+    }
+
+    // ---- test_route_parse_roundtrip ---------------------------------------
+
+    @Test
+    @DisplayName("test_route_parse_roundtrip: parse -> toUrl -> parse produces equal routes")
+    void test_route_parse_roundtrip() {
+        String original = "ortho://proof/rtl_deterministic";
+        OrthoRoute route = OrthoRoute.parse(original);
+        assertNotNull(route);
+        assertInstanceOf(OrthoRoute.ProofRoute.class, route);
+
+        String serialized = route.toUrl();
+        assertEquals(original, serialized, "toUrl must be canonical");
+
+        OrthoRoute reparsed = OrthoRoute.parse(serialized);
+        assertEquals(route, reparsed, "parse -> toUrl -> parse must produce equal routes");
+        assertEquals(reparsed.toUrl(), original);
+
+        // Additional round-trips
+        String[] urls = {
+            "ortho://app/terminal",
+            "ortho://trace/cycle/420",
+            "ortho://hardware/device/ortho0?op=tensor",
+            "ortho://ide/file/rtl/fabric/arbiter.sv?line=184",
+            "ortho://settings/security",
+            "https://github.com/ortho/ortho32"
+        };
+        for (String url : urls) {
+            OrthoRoute r = OrthoRoute.parse(url);
+            assertEquals(url, r.toUrl(), "round-trip failed for " + url);
+            assertEquals(r, OrthoRoute.parse(r.toUrl()));
+        }
+    }
+
+    // ---- test_agent_uses_intent_route -------------------------------------
+
+    @Test
+    @DisplayName("test_agent_uses_intent_route: agent dispatches IntentRoute not direct state mutation")
+    void test_agent_uses_intent_route() throws Exception {
+        // Simulate agent – must use OrthoRoute.IntentRoute, never raw string or direct state
+        OrthoRouteContext agentCtx = OrthoRouteContext.forAgent("agent-verify-1", session.sessionId(), "proofExecute");
+
+        // Agent creates a typed IntentRoute – not a raw String
+        OrthoRoute.IntentRoute intent = new OrthoRoute.IntentRoute("proof.verify", "rtl_deterministic", Map.of("mode","check"));
+        assertNotNull(intent.intent());
+        assertNotNull(intent.target());
+        assertEquals("proof.verify", intent.intent());
+
+        // Dispatch via router – this is the ONLY allowed path
+        OrthoRouteResult result = router.perform(intent, agentCtx).get(2, TimeUnit.SECONDS);
+
+        assertInstanceOf(OrthoRouteResult.Success.class, result);
+        OrthoRouteResult.Success success = (OrthoRouteResult.Success) result;
+        assertNotNull(success.output());
+        assertTrue(success.output().toString().contains("proof.verify"));
+
+        // Verify we did not mutate state directly – router path was IntentRoute
+        // The following would not compile if raw string routing were used:
+        // router.perform("proof.verify", ...) // <-- no such method, typed route required
+        assertInstanceOf(OrthoRoute.IntentRoute.class, intent);
+
+        // Ensure no direct State mutation API exists on the agent – compile-time guarantee
+        // If agent tried: agent.state.set(...), it would not exist; only router.perform is available
+        // We verify the intent round-trips via URL as well (same language as Swift)
+        String url = intent.toUrl();
+        assertTrue(url.startsWith("ortho://intent/"));
+        OrthoRoute reparsed = OrthoRoute.parse(url);
+        assertInstanceOf(OrthoRoute.IntentRoute.class, reparsed);
+        assertEquals(intent, reparsed);
+    }
+
+    // ---- test_hardware_route_is_typed -------------------------------------
+
+    @Test
+    @DisplayName("test_hardware_route_is_typed: HardwareRoute fields are typed not raw strings")
+    void test_hardware_route_is_typed() throws Exception {
+        // HardwareRoute must have typed fields device: String, operation: String, params: Map
+        OrthoRoute.HardwareRoute hw = new OrthoRoute.HardwareRoute("ortho0", "tensor", Map.of("dtype","fp8"));
+        assertEquals("ortho0", hw.device());
+        assertEquals("tensor", hw.operation());
+        assertEquals("fp8", hw.params().get("dtype"));
+
+        // toUrl is structured, not ad-hoc string concatenation
+        String url = hw.toUrl();
+        assertTrue(url.startsWith("ortho://hardware/device/ortho0"));
+        assertTrue(url.contains("op=tensor"));
+
+        OrthoRoute parsed = OrthoRoute.parse(url);
+        assertInstanceOf(OrthoRoute.HardwareRoute.class, parsed);
+        OrthoRoute.HardwareRoute reparsed = (OrthoRoute.HardwareRoute) parsed;
+        assertEquals(hw.device(), reparsed.device());
+        assertEquals(hw.operation(), reparsed.operation());
+
+        // Perform via router – goes through HardwareRouter -> ORTHOBridge (SimulatorTransport) – not raw PCIe
+        OrthoRouteContext hwCtx = new OrthoRouteContext("hw-test", null, session.sessionId(), "hardwareAccess", Instant.now());
+        OrthoRouteResult result = router.perform(hw, hwCtx).get(2, TimeUnit.SECONDS);
+        // SimulatorTransport returns success
+        assertInstanceOf(OrthoRouteResult.Success.class, result);
+    }
+
+    // ---- test_route_result_sealed -----------------------------------------
+
+    @Test
+    @DisplayName("test_route_result_sealed: RouteResult is sealed – compiler forces handling all cases")
+    void test_route_result_sealed() throws Exception {
+        OrthoRoute route = OrthoRoute.parse("ortho://app/terminal");
+        OrthoRouteResult result = router.open(route, adminContext).get(2, TimeUnit.SECONDS);
+
+        // Exhaustive switch – compiler enforces all sealed permits; this must compile with --enable-preview
+        String handled = switch (result) {
+            case OrthoRouteResult.Success s -> "success:" + s.windowId();
+            case OrthoRouteResult.Failure f -> "failure:" + f.error().name();
+            case OrthoRouteResult.Deferred d -> "deferred:" + d.id();
+        };
+        assertNotNull(handled);
+        assertTrue(handled.startsWith("success:"));
+
+        // Failure case also exercises sealed handling
+        OrthoRouteContext noCap = new OrthoRouteContext("user", null, session.sessionId(), "readOnly", Instant.now());
+        OrthoRoute.HardwareRoute hw = new OrthoRoute.HardwareRoute("ortho0", "tensor", Map.of());
+        OrthoRouteResult denied = router.perform(hw, noCap).get(2, TimeUnit.SECONDS);
+        String handledDenied = switch (denied) {
+            case OrthoRouteResult.Success s -> "success";
+            case OrthoRouteResult.Failure f -> {
+                assertEquals(OrthoRouteError.CAPABILITY_DENIED, f.error());
+                yield "failure:" + f.error();
+            }
+            case OrthoRouteResult.Deferred d -> "deferred";
+        };
+        assertEquals("failure:CAPABILITY_DENIED", handledDenied);
+
+        // Verify router is sealed result – no raw string status
+        assertTrue(OrthoRouteResult.class.isSealed(), "OrthoRouteResult must be sealed");
+        assertEquals(3, OrthoRouteResult.class.getPermittedSubclasses().length);
+    }
+
+    @Test
+    @DisplayName("router obtained only via OrthoSession.router() – constructor not public")
+    void test_router_not_directly_constructed() {
+        // Verify OrthoRouter has no public constructor – only OrthoSession can create it
+        var ctors = OrthoRouter.class.getDeclaredConstructors();
+        for (var c : ctors) {
+            assertFalse(java.lang.reflect.Modifier.isPublic(c.getModifiers()), "OrthoRouter must not have public constructor – use OrthoSession.router()");
+        }
+        // The only way to get a router is via session
+        OrthoRouter r1 = session.router();
+        OrthoRouter r2 = session.router();
+        assertSame(r1, r2, "Same session must return same router instance");
+    }
+}

integration-tests/src/test/java/org/ortho32/tests/SessionLifecycleTest.java

@@ -0,0 +1,65 @@
+package org.ortho32.tests;
+
+import org.junit.jupiter.api.Test;
+import static org.junit.jupiter.api.Assertions.*;
+
+import org.ortho32.OrthoRuntime;
+import org.ortho32.OrthoSession;
+import org.ortho32.transport.SimulatorTransport;
+
+public class SessionLifecycleTest {
+
+    @Test
+    public void sessionLifecycleUsesAllSubclientsAndCleansUp() throws Exception {
+        SimulatorTransport transport = new SimulatorTransport();
+        OrthoRuntime runtime = openRuntime(transport);
+        assertNotNull(runtime);
+
+        OrthoSession session = runtime.openSession();
+        assertNotNull(session);
+        assertTrue(session instanceof AutoCloseable, "OrthoSession must be AutoCloseable");
+
+        // Use all sub-clients as per OrthoSession API
+        assertNotNull(session.devices(), "devices() must be present");
+        assertNotNull(session.tensor(), "tensor() must be present");
+        assertNotNull(session.trace(), "trace() must be present");
+        assertNotNull(session.verify(), "verify() must be present");
+        assertNotNull(session.security(), "security() must be present");
+        assertNotNull(session.agent(), "agent() must be present");
+
+        // Exercise devices
+        var devices = session.devices().list();
+        assertNotNull(devices);
+
+        // Context and version
+        assertNotNull(session.context(), "context must be present");
+        assertNotNull(runtime.version(), "version must be present");
+
+        // AutoCloseable cleanup via close()
+        session.close();
+        runtime.close();
+
+        // Verify closed resources throw or are marked closed
+        // After close, opening a new session on closed runtime should fail or new runtime works
+        try (OrthoRuntime r2 = openRuntime(new SimulatorTransport());
+             OrthoSession s2 = r2.openSession()) {
+            assertNotNull(s2.devices());
+        }
+
+        // Try-with-resources path
+        try (OrthoRuntime r3 = openRuntime(new SimulatorTransport());
+             OrthoSession s3 = r3.openSession()) {
+            assertDoesNotThrow(() -> s3.devices().list());
+        }
+    }
+
+    private static OrthoRuntime openRuntime(SimulatorTransport transport) {
+        for (var m : OrthoRuntime.class.getMethods()) {
+            if (m.getName().equals("open") && m.getParameterCount()==1
+                    && m.getParameterTypes()[0].isAssignableFrom(transport.getClass())) {
+                try { return (OrthoRuntime) m.invoke(null, transport); } catch (Exception e) { throw new RuntimeException(e); }
+            }
+        }
+        return OrthoRuntime.open();
+    }
+}

integration-tests/src/test/java/org/ortho32/tests/SimulatorTransportTest.java

@@ -0,0 +1,49 @@
+package org.ortho32.tests;
+
+import org.junit.jupiter.api.Test;
+import static org.junit.jupiter.api.Assertions.*;
+
+import org.ortho32.fabric.FabricAddress;
+import org.ortho32.fabric.FabricCommand;
+import org.ortho32.fabric.FabricCompletion;
+import org.ortho32.fabric.FabricOpcode;
+import org.ortho32.transport.SimulatorTransport;
+
+import java.util.concurrent.TimeUnit;
+
+public class SimulatorTransportTest {
+
+    @Test
+    public void connectAndSubmitFabricCommandVerifiesArchitecturalCycles() throws Exception {
+        SimulatorTransport transport = new SimulatorTransport();
+        transport.connect();
+
+        long sequence = 42L;
+        FabricCommand cmd = FabricCommand.builder()
+                .opcode(FabricOpcode.TENSOR)
+                .device("sim0")
+                .address(new FabricAddress(0x1000L))
+                .length(64)
+                .epoch(0)
+                .slot(0)
+                .sequence(sequence)
+                .payloadHash("a".repeat(64))
+                .flags(0)
+                .build();
+
+        // SimulatorTransport is deterministic fake fabric - no hardware
+        FabricCompletion completion = transport.submit(cmd).get(5, TimeUnit.SECONDS);
+
+        assertNotNull(completion, "completion must not be null");
+        assertEquals(sequence, completion.sequence(), "completion sequence must echo command sequence");
+        assertNotNull(completion.status(), "status must be present");
+        // Cycles are architectural integers, not wall-clock
+        assertTrue(completion.acceptedCycle() >= 0, "acceptedCycle must be >=0 architectural cycle");
+        assertTrue(completion.completionCycle() >= completion.acceptedCycle(),
+                "completionCycle must be >= acceptedCycle (architectural)");
+        assertNotNull(completion.resultHash(), "resultHash must be present");
+        assertNotNull(completion.traceRoot(), "traceRoot must be present");
+
+        transport.disconnect();
+    }
+}

integration-tests/src/test/java/org/ortho32/tests/TensorJobTest.java

@@ -0,0 +1,64 @@
+package org.ortho32.tests;
+
+import org.junit.jupiter.api.Test;
+import static org.junit.jupiter.api.Assertions.*;
+
+import org.ortho32.OrthoRuntime;
+import org.ortho32.OrthoSession;
+import org.ortho32.device.OrthoDevice;
+import org.ortho32.tensor.Tensor;
+import org.ortho32.tensor.TensorJob;
+import org.ortho32.tensor.TensorLatency;
+import org.ortho32.tensor.TensorOperation;
+import org.ortho32.tensor.TensorResult;
+import org.ortho32.tensor.TensorShape;
+import org.ortho32.transport.SimulatorTransport;
+
+public class TensorJobTest {
+
+    @Test
+    public void submitTMUL4x4VerifiesLatencyAndTraceHash() throws Exception {
+        SimulatorTransport transport = new SimulatorTransport();
+        try (OrthoRuntime runtime = openRuntime(transport);
+             OrthoSession session = runtime.openSession()) {
+
+            OrthoDevice device = session.devices().firstAvailable();
+            assertNotNull(device, "firstAvailable device must exist on simulator");
+
+            TensorShape shape = new TensorShape(4, 4);
+            float[] a = new float[16];
+            float[] b = new float[16];
+            for (int i = 0; i < 16; i++) { a[i] = i; b[i] = i; }
+
+            Tensor tensorA = Tensor.of(shape, a);
+            Tensor tensorB = Tensor.of(shape, b);
+
+            TensorJob job = TensorJob.builder()
+                    .device(device)
+                    .operation(TensorOperation.TMUL)
+                    .inputA(tensorA)
+                    .inputB(tensorB)
+                    .build();
+
+            TensorResult result = session.tensor().submit(job).join();
+
+            // TensorLatency.TMUL_CYCLES is architectural constant 4L, never wall-clock
+            assertEquals(TensorLatency.TMUL_CYCLES, result.cycles(),
+                    "TMUL must take exactly TMUL_CYCLES architectural cycles");
+            assertEquals(4L, result.cycles(), "TMUL_CYCLES must be 4");
+            assertNotNull(result.traceHash(), "traceHash must be non-null");
+            assertNotNull(result.output(), "output must be present");
+            assertTrue(result.completionCycle() >= 0, "completionCycle architectural");
+        }
+    }
+
+    private static OrthoRuntime openRuntime(SimulatorTransport transport) {
+        for (var m : OrthoRuntime.class.getMethods()) {
+            if (m.getName().equals("open") && m.getParameterCount()==1
+                    && m.getParameterTypes()[0].isAssignableFrom(transport.getClass())) {
+                try { return (OrthoRuntime) m.invoke(null, transport); } catch (Exception e) { throw new RuntimeException(e); }
+            }
+        }
+        return OrthoRuntime.open();
+    }
+}

integration-tests/src/test/java/org/ortho32/tests/TraceComparatorTest.java

@@ -0,0 +1,62 @@
+package org.ortho32.tests;
+
+import org.junit.jupiter.api.Test;
+import static org.junit.jupiter.api.Assertions.*;
+
+import org.ortho32.trace.CycleRecord;
+import org.ortho32.trace.ExecutionTrace;
+import org.ortho32.trace.TraceComparison;
+import org.ortho32.trace.TraceComparator;
+
+import java.util.ArrayList;
+import java.util.List;
+
+public class TraceComparatorTest {
+
+    @Test
+    public void identicalTracesAreEqualAndMutatedAreNot() {
+        ExecutionTrace t1 = sampleTrace();
+        ExecutionTrace t2 = sampleTrace();
+
+        TraceComparison eq = TraceComparator.compare(t1, t2);
+        assertTrue(eq.isEqual(), "identical traces must be equal");
+        assertTrue(eq.mismatches().isEmpty(), "no mismatches for identical traces");
+
+        // Mutate one cycle
+        ExecutionTrace mutated = mutate(t1);
+        TraceComparison neq = TraceComparator.compare(t1, mutated);
+        assertFalse(neq.isEqual(), "mutated trace must not be equal");
+        assertFalse(neq.mismatches().isEmpty(), "mismatches must be reported");
+    }
+
+    private ExecutionTrace sampleTrace() {
+        List<CycleRecord> cycles = new ArrayList<>();
+        for (int i = 0; i < 4; i++) {
+            cycles.add(new CycleRecord(
+                    i,
+                    "EX",
+                    "TMUL",
+                    "COMMITTED",
+                    List.of(new CycleRecord.RegisterWrite("r" + i, "0x" + i)),
+                    List.of()
+            ));
+        }
+        return new ExecutionTrace(cycles);
+    }
+
+    private ExecutionTrace mutate(ExecutionTrace original) {
+        List<CycleRecord> cycles = new ArrayList<>(original.cycles());
+        // flip first cycle's commitStatus
+        CycleRecord first = cycles.get(0);
+        CycleRecord mutated = new CycleRecord(
+                first.cycleNumber(),
+                first.scalarStage(),
+                first.tensorStage(),
+                "FLUSHED",
+                first.registerWrites(),
+                first.memoryEvents()
+        );
+        cycles.set(0, mutated);
+        return new ExecutionTrace(cycles);
+    }
+}

integration-tests/src/test/java/org/ortho32/tests/TransportAgnosticTest.java

@@ -0,0 +1,60 @@
+package org.ortho32.tests;
+
+import org.junit.jupiter.api.Test;
+import static org.junit.jupiter.api.Assertions.*;
+
+import org.ortho32.OrthoRuntime;
+import org.ortho32.OrthoSession;
+import org.ortho32.device.OrthoDevice;
+import org.ortho32.tensor.Tensor;
+import org.ortho32.tensor.TensorJob;
+import org.ortho32.tensor.TensorLatency;
+import org.ortho32.tensor.TensorOperation;
+import org.ortho32.tensor.TensorResult;
+import org.ortho32.tensor.TensorShape;
+
+/**
+ * This test must import ZERO transport-specific classes.
+ * It verifies the same OrthoSession API works with SimulatorTransport
+ * without any transport-specific import in the test class.
+ */
+public class TransportAgnosticTest {
+
+    @Test
+    public void sameOrthoSessionApiWorksWithoutTransportImport() throws Exception {
+        // No SimulatorTransport import - OrthoRuntime.open() defaults to simulator in test env
+        try (OrthoRuntime runtime = OrthoRuntime.open();
+             OrthoSession session = runtime.openSession()) {
+
+            assertNotNull(runtime.version(), "version must be available");
+            assertNotNull(session.devices());
+            assertNotNull(session.tensor());
+            assertNotNull(session.trace());
+            assertNotNull(session.verify());
+            assertNotNull(session.agent());
+            assertNotNull(session.security());
+
+            OrthoDevice device = session.devices().firstAvailable();
+            assertNotNull(device, "device must be available via agnostic API");
+
+            TensorShape shape = new TensorShape(4, 4);
+            float[] data = new float[16];
+            for (int i = 0; i < 16; i++) data[i] = i + 1;
+            Tensor a = Tensor.of(shape, data);
+            Tensor b = Tensor.of(shape, data);
+
+            TensorJob job = TensorJob.builder()
+                    .device(device)
+                    .operation(TensorOperation.TMUL)
+                    .inputA(a)
+                    .inputB(b)
+                    .build();
+
+            TensorResult result = session.tensor().submit(job).join();
+            assertNotNull(result);
+            assertEquals(TensorLatency.TMUL_CYCLES, result.cycles(),
+                    "Agnostic API must still return architectural TMUL cycles");
+            assertNotNull(result.traceHash());
+        }
+    }
+}

integration-tests/src/test/java/org/ortho32/tests/VerificationStatusTest.java

@@ -0,0 +1,30 @@
+package org.ortho32.tests;
+
+import org.junit.jupiter.api.Test;
+import static org.junit.jupiter.api.Assertions.*;
+
+import org.ortho32.verify.VerificationStatus;
+
+public class VerificationStatusTest {
+
+    @Test
+    public void verifiedIsFormallyVerifiedAndTestedIsNotAndNeverInterchangeable() {
+        assertTrue(VerificationStatus.VERIFIED.isFormallyVerified(),
+                "VERIFIED must be formally verified");
+        assertFalse(VerificationStatus.TESTED.isFormallyVerified(),
+                "TESTED must NOT be formally verified");
+
+        assertNotEquals(VerificationStatus.VERIFIED, VerificationStatus.TESTED,
+                "VERIFIED != TESTED - never interchangeable");
+
+        // Additional invariants
+        assertTrue(VerificationStatus.CROSS_VERIFIED.isFormallyVerified(),
+                "CROSS_VERIFIED must be formally verified");
+        assertFalse(VerificationStatus.ASSUMED.isFormallyVerified(),
+                "ASSUMED must not be formally verified");
+        assertFalse(VerificationStatus.FAILED.isFormallyVerified(),
+                "FAILED must not be formally verified");
+        assertFalse(VerificationStatus.UNVERIFIED.isFormallyVerified(),
+                "UNVERIFIED must not be formally verified");
+    }
+}

ortho-agent/build.gradle.kts

@@ -0,0 +1,7 @@
+plugins { `java-library` }
+
+dependencies {
+    api(project(":ortho-fabric"))
+    api(project(":ortho-device"))
+    api(project(":ortho-security"))
+}

ortho-agent/src/main/java/org/ortho32/agent/AgentCapability.java

@@ -0,0 +1,33 @@
+package org.ortho32.agent;
+
+import java.util.Objects;
+
+/**
+ * Capability advertised by an agent.
+ *
+ * @param id stable capability identifier, must not be null
+ * @param name human-readable name, must not be null
+ * @param description description, must not be null
+ * @param resourceLimit resource limit for this capability, must be >=0
+ */
+public record AgentCapability(
+        String id,
+        String name,
+        String description,
+        long resourceLimit) {
+
+    /**
+     * Compact canonical constructor.
+     *
+     * @param id capability id
+     * @param name name
+     * @param description description
+     * @param resourceLimit resource limit
+     */
+    public AgentCapability {
+        Objects.requireNonNull(id, "id");
+        Objects.requireNonNull(name, "name");
+        Objects.requireNonNull(description, "description");
+        if (resourceLimit < 0) throw new IllegalArgumentException("resourceLimit must be >=0");
+    }
+}

ortho-agent/src/main/java/org/ortho32/agent/AgentClient.java

@@ -0,0 +1,26 @@
+package org.ortho32.agent;
+
+import java.util.List;
+import java.util.Objects;
+import java.util.concurrent.CompletableFuture;
+
+/**
+ * Session sub-client for agent dispatch.
+ */
+public interface AgentClient {
+
+    /**
+     * Dispatches a task to an agent.
+     *
+     * @param task task to dispatch, must not be null
+     * @return future completing with agent result containing architectural cycles
+     */
+    CompletableFuture<AgentResult> dispatch(AgentTask task);
+
+    /**
+     * Lists intents supported by the agent.
+     *
+     * @return unmodifiable list of intents, never null
+     */
+    List<AgentIntent> intents();
+}

ortho-agent/src/main/java/org/ortho32/agent/AgentIntent.java

@@ -0,0 +1,40 @@
+package org.ortho32.agent;
+
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+
+/**
+ * Typed intent describing an agent action.
+ *
+ * @param id stable intent identifier, must not be null
+ * @param verb action verb, must not be null
+ * @param noun target noun, must not be null
+ * @param parameters parameter map, never null, unmodifiable
+ * @param requiredCapabilities required capabilities for execution, never null, unmodifiable
+ */
+public record AgentIntent(
+        String id,
+        String verb,
+        String noun,
+        Map<String, String> parameters,
+        List<String> requiredCapabilities) {
+
+    /**
+     * Compact canonical constructor.
+     *
+     * @param id intent id
+     * @param verb verb
+     * @param noun noun
+     * @param parameters parameters
+     * @param requiredCapabilities required capabilities
+     */
+    public AgentIntent {
+        Objects.requireNonNull(id, "id");
+        Objects.requireNonNull(verb, "verb");
+        Objects.requireNonNull(noun, "noun");
+        Objects.requireNonNull(requiredCapabilities, "requiredCapabilities");
+        parameters = parameters == null ? Map.of() : Map.copyOf(parameters);
+        requiredCapabilities = List.copyOf(requiredCapabilities);
+    }
+}

ortho-agent/src/main/java/org/ortho32/agent/AgentResult.java

@@ -0,0 +1,36 @@
+package org.ortho32.agent;
+
+import java.util.Objects;
+
+/**
+ * Result of an agent task.
+ *
+ * @param taskId originating task id, must not be null
+ * @param status status string, must not be null
+ * @param output output payload, may be null
+ * @param cycles architectural cycles consumed, never wall-clock
+ * @param auditId audit identifier for traceability, must not be null
+ */
+public record AgentResult(
+        String taskId,
+        String status,
+        String output,
+        long cycles,
+        String auditId) {
+
+    /**
+     * Compact canonical constructor.
+     *
+     * @param taskId task id
+     * @param status status
+     * @param output output
+     * @param cycles architectural cycles
+     * @param auditId audit id
+     */
+    public AgentResult {
+        Objects.requireNonNull(taskId, "taskId");
+        Objects.requireNonNull(status, "status");
+        Objects.requireNonNull(auditId, "auditId");
+        if (cycles < 0) throw new IllegalArgumentException("cycles must be >=0");
+    }
+}

ortho-agent/src/main/java/org/ortho32/agent/AgentTask.java

@@ -0,0 +1,32 @@
+package org.ortho32.agent;
+
+import java.util.Objects;
+
+/**
+ * Task submitted to an agent.
+ *
+ * @param id task identifier, must not be null
+ * @param intent intent to execute, must not be null
+ * @param context context string for execution, may be null
+ * @param timeout timeout in milliseconds, must be >=0
+ */
+public record AgentTask(
+        String id,
+        AgentIntent intent,
+        String context,
+        long timeout) {
+
+    /**
+     * Compact canonical constructor.
+     *
+     * @param id task id
+     * @param intent intent
+     * @param context context
+     * @param timeout timeout
+     */
+    public AgentTask {
+        Objects.requireNonNull(id, "id");
+        Objects.requireNonNull(intent, "intent");
+        if (timeout < 0) throw new IllegalArgumentException("timeout must be >=0");
+    }
+}

ortho-compute/build.gradle.kts

@@ -0,0 +1,12 @@
+plugins {
+    `java-library`
+}
+
+dependencies {
+    api(project(":ortho-device"))
+    api(project(":ortho-fabric"))
+}
+
+java {
+    toolchain { languageVersion.set(JavaLanguageVersion.of(21)) }
+}

ortho-compute/src/main/java/org/ortho32/compute/ComputeBackend.java

@@ -0,0 +1,7 @@
+package org.ortho32.compute;
+
+public enum ComputeBackend {
+    ORTHO,
+    CUDA_REFERENCE,
+    SIMULATOR
+}

ortho-compute/src/main/java/org/ortho32/compute/ComputeJob.java

@@ -0,0 +1,42 @@
+package org.ortho32.compute;
+
+import org.ortho32.device.OrthoDeviceId;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Objects;
+
+/**
+ * Immutable compute job descriptor.
+ *
+ * @param device target device id
+ * @param backend execution backend
+ * @param options immutable options map
+ * @param payload opaque payload (defensive copy)
+ */
+public record ComputeJob(
+        OrthoDeviceId device,
+        ComputeBackend backend,
+        Map<String, String> options,
+        byte[] payload
+) {
+    public ComputeJob {
+        Objects.requireNonNull(device);
+        Objects.requireNonNull(backend);
+        if (options == null) options = Map.of();
+        options = Collections.unmodifiableMap(new HashMap<>(options));
+        if (payload == null) payload = new byte[0];
+        payload = Arrays.copyOf(payload, payload.length);
+    }
+
+    @Override
+    public Map<String, String> options() {
+        return Collections.unmodifiableMap(options);
+    }
+
+    @Override
+    public byte[] payload() {
+        return Arrays.copyOf(payload, payload.length);
+    }
+}

ortho-compute/src/main/java/org/ortho32/compute/ComputeResult.java

@@ -0,0 +1,31 @@
+package org.ortho32.compute;
+
+import java.util.Arrays;
+import java.util.Objects;
+
+/**
+ * Immutable compute result with architectural cycle accounting.
+ *
+ * @param status execution status
+ * @param output output bytes (defensive copy)
+ * @param cycles architectural cycles (long, never wall-clock)
+ * @param traceHash trace hash (SHA-256 hex)
+ */
+public record ComputeResult(
+        String status,
+        byte[] output,
+        long cycles,
+        String traceHash
+) {
+    public ComputeResult {
+        Objects.requireNonNull(status);
+        Objects.requireNonNull(traceHash);
+        if (output == null) output = new byte[0];
+        output = Arrays.copyOf(output, output.length);
+    }
+
+    @Override
+    public byte[] output() {
+        return Arrays.copyOf(output, output.length);
+    }
+}

ortho-core/build.gradle.kts

@@ -0,0 +1,15 @@
+// ortho-core: top-level aggregator. OrthoRuntime/OrthoSession compose all sub-clients.
+plugins { `java-library` }
+
+dependencies {
+    api(project(":ortho-fabric"))
+    api(project(":ortho-device"))
+    api(project(":ortho-transport"))
+    api(project(":ortho-compute"))
+    api(project(":ortho-tensor"))
+    api(project(":ortho-trace"))
+    api(project(":ortho-verify"))
+    api(project(":ortho-security"))
+    api(project(":ortho-agent"))
+    api(project(":ortho-routing"))
+}

ortho-core/src/main/java/org/ortho32/OrthoContext.java

@@ -0,0 +1,24 @@
+package org.ortho32;
+
+import java.util.Set;
+
+/**
+ * Session context: immutable snapshot of session identity, capabilities and activity.
+ *
+ * @param identity stable session identifier
+ * @param capabilities granted capabilities
+ * @param active whether session is active
+ * @param requestCount number of requests issued in this session
+ */
+public record OrthoContext(
+        String identity,
+        Set<String> capabilities,
+        boolean active,
+        long requestCount
+) {
+    public OrthoContext {
+        if (identity == null) throw new IllegalArgumentException("identity is null");
+        if (capabilities == null) throw new IllegalArgumentException("capabilities is null");
+        capabilities = Set.copyOf(capabilities);
+    }
+}

ortho-core/src/main/java/org/ortho32/OrthoResult.java

@@ -0,0 +1,31 @@
+package org.ortho32;
+
+import java.util.Arrays;
+import java.util.Objects;
+
+/**
+ * Typed result with architectural cycle accounting.
+ *
+ * @param status result status
+ * @param payload opaque payload bytes (defensive copy)
+ * @param cycles architectural cycles (long, never wall-clock)
+ * @param traceHash SHA-256 of canonical trace or empty
+ */
+public record OrthoResult(
+        String status,
+        byte[] payload,
+        long cycles,
+        String traceHash
+) {
+    public OrthoResult {
+        Objects.requireNonNull(status, "status");
+        Objects.requireNonNull(traceHash, "traceHash");
+        if (payload == null) payload = new byte[0];
+        payload = Arrays.copyOf(payload, payload.length);
+    }
+
+    @Override
+    public byte[] payload() {
+        return Arrays.copyOf(payload, payload.length);
+    }
+}

ortho-core/src/main/java/org/ortho32/OrthoRuntime.java

@@ -0,0 +1,59 @@
+package org.ortho32;
+
+import org.ortho32.transport.SimulatorTransport;
+import org.ortho32.transport.TransportFactory;
+import org.ortho32.transport.OrthoTransport;
+
+/**
+ * Entry point for ORTHO-32 SDK.
+ * Applications obtain a runtime via {@link #open()} and then open sessions.
+ */
+public final class OrthoRuntime implements AutoCloseable {
+
+    private final OrthoTransport transport;
+    private volatile boolean closed;
+
+    private OrthoRuntime(OrthoTransport transport) {
+        this.transport = transport;
+        this.transport.connect();
+    }
+
+    /**
+     * Open a runtime backed by SimulatorTransport (deterministic, no hardware).
+     */
+    public static OrthoRuntime open() {
+        return new OrthoRuntime(TransportFactory.simulator());
+    }
+
+    /**
+     * Open with an explicit transport (internal use). Public surface uses {@link #open()}.
+     */
+    static OrthoRuntime open(OrthoTransport transport) {
+        return new OrthoRuntime(transport);
+    }
+
+    public OrthoSession openSession() {
+        if (closed) {
+            throw new IllegalStateException("OrthoRuntime is closed");
+        }
+        OrthoContext context = new OrthoContext(
+                "ortho32-session-" + System.nanoTime(),
+                java.util.Set.of("tensor", "trace", "verify"),
+                true,
+                0L
+        );
+        return new OrthoSession(context, transport);
+    }
+
+    public OrthoVersion version() {
+        return new OrthoVersion("0.1.0", "1.0.0", "32-1.0");
+    }
+
+    @Override
+    public void close() {
+        if (!closed) {
+            closed = true;
+            transport.disconnect();
+        }
+    }
+}

ortho-core/src/main/java/org/ortho32/OrthoSession.java

@@ -0,0 +1,86 @@
+package org.ortho32;
+
+import org.ortho32.device.DeviceClient;
+import org.ortho32.transport.OrthoTransport;
+import java.util.Objects;
+import java.util.concurrent.atomic.AtomicLong;
+
+/**
+ * Session is the main interaction scope. AutoCloseable. Provides sub-clients.
+ */
+public final class OrthoSession implements AutoCloseable {
+
+    private final OrthoContext context;
+    private final OrthoTransport transport;
+    private final AtomicLong requestCount = new AtomicLong(0);
+    private final DeviceClient devices;
+
+    // Stub sub-clients for modules not yet wired in this slice
+    public interface TensorClient {
+        java.util.concurrent.CompletableFuture<org.ortho32.compute.ComputeResult> submit(org.ortho32.compute.ComputeJob job);
+    }
+    public interface TraceClient {}
+    public interface VerifyClient {}
+    public interface AgentClient {}
+    public interface SecurityClient {}
+
+    private final TensorClient tensorClient;
+    private final TraceClient traceClient;
+    private final VerifyClient verifyClient;
+    private final AgentClient agentClient;
+    private final SecurityClient securityClient;
+
+    OrthoSession(OrthoContext context, OrthoTransport transport) {
+        this.context = Objects.requireNonNull(context);
+        this.transport = Objects.requireNonNull(transport);
+        this.devices = new DeviceClient(transport);
+        this.tensorClient = job -> java.util.concurrent.CompletableFuture.failedFuture(
+                new UnsupportedOperationException("tensor not wired in core slice"));
+        this.traceClient = new TraceClient() {};
+        this.verifyClient = new VerifyClient() {};
+        this.agentClient = new AgentClient() {};
+        this.securityClient = new SecurityClient() {};
+    }
+
+    public OrthoContext context() {
+        return new OrthoContext(
+                context.identity(),
+                context.capabilities(),
+                context.active(),
+                requestCount.get()
+        );
+    }
+
+    long nextRequestId() {
+        return requestCount.incrementAndGet();
+    }
+
+    public DeviceClient devices() {
+        return devices;
+    }
+
+    public TensorClient tensor() {
+        return tensorClient;
+    }
+
+    public TraceClient trace() {
+        return traceClient;
+    }
+
+    public VerifyClient verify() {
+        return verifyClient;
+    }
+
+    public AgentClient agent() {
+        return agentClient;
+    }
+
+    public SecurityClient security() {
+        return securityClient;
+    }
+
+    @Override
+    public void close() {
+        // no-op for simulator; disconnect is owned by runtime
+    }
+}

ortho-core/src/main/java/org/ortho32/OrthoVersion.java

@@ -0,0 +1,20 @@
+package org.ortho32;
+
+/**
+ * Compatibility tuple for SDK + Fabric Protocol + Device ABI.
+ *
+ * @param sdkVersion SDK semantic version
+ * @param fabricProtocolVersion fabric protocol version
+ * @param deviceABIVersion device ABI version
+ */
+public record OrthoVersion(
+        String sdkVersion,
+        String fabricProtocolVersion,
+        String deviceABIVersion
+) {
+    public OrthoVersion {
+        if (sdkVersion == null || fabricProtocolVersion == null || deviceABIVersion == null) {
+            throw new IllegalArgumentException("version components must not be null");
+        }
+    }
+}

ortho-device/build.gradle.kts

@@ -0,0 +1,11 @@
+plugins {
+    `java-library`
+}
+
+dependencies {
+    api(project(":ortho-fabric"))
+}
+
+java {
+    toolchain { languageVersion.set(JavaLanguageVersion.of(21)) }
+}

ortho-device/src/main/java/org/ortho32/device/DeviceClient.java

@@ -0,0 +1,57 @@
+package org.ortho32.device;
+
+import org.ortho32.transport.OrthoTransport;
+import java.util.List;
+import java.util.Objects;
+import java.util.Optional;
+
+/**
+ * Session sub-client for device enumeration. Immutable, thread-safe.
+ */
+public final class DeviceClient {
+
+    private final List<OrthoDevice> devices;
+
+    public DeviceClient(OrthoTransport transport) {
+        Objects.requireNonNull(transport);
+        // Deterministic simulator device set. In real transports this would query host service.
+        OrthoDevice sim = new SimulatedDevice();
+        this.devices = List.of(sim);
+    }
+
+    // Test constructor
+    DeviceClient(List<OrthoDevice> devices) {
+        this.devices = List.copyOf(Objects.requireNonNull(devices));
+    }
+
+    public OrthoDevice firstAvailable() {
+        return devices.stream()
+                .filter(d -> d.state() != OrthoDeviceState.ERROR)
+                .findFirst()
+                .orElseThrow(() -> new java.util.NoSuchElementException("No available ORTHO device"));
+    }
+
+    public List<OrthoDevice> list() {
+        return devices;
+    }
+
+    public Optional<OrthoDevice> find(OrthoDeviceId id) {
+        Objects.requireNonNull(id);
+        return devices.stream().filter(d -> d.id().equals(id)).findFirst();
+    }
+
+    private static final class SimulatedDevice implements OrthoDevice {
+        private final OrthoDeviceId id = new OrthoDeviceId("sim-0001");
+        private final OrthoDeviceInfo info = new OrthoDeviceInfo("ORTHO-32 Simulator", "simulator", "ortho-32", "0.1.0-sim");
+        private final OrthoDeviceCapabilities caps = new OrthoDeviceCapabilities(true, true, true, 1 << 20);
+        private volatile OrthoDeviceState state = OrthoDeviceState.CONNECTED;
+
+        @Override public OrthoDeviceId id() { return id; }
+        @Override public OrthoDeviceInfo info() { return info; }
+        @Override public OrthoDeviceCapabilities capabilities() { return caps; }
+        @Override public OrthoDeviceState state() { return state; }
+        @Override public void connect() { state = OrthoDeviceState.CONNECTED; }
+        @Override public void disconnect() { state = OrthoDeviceState.DISCONNECTED; }
+        @Override public void reset() { state = OrthoDeviceState.CONNECTED; }
+    }
+}

ortho-device/src/main/java/org/ortho32/device/OrthoDevice.java

@@ -0,0 +1,21 @@
+package org.ortho32.device;
+
+/**
+ * Public device handle. Applications interact via this interface, never via transport internals.
+ */
+public interface OrthoDevice {
+
+    OrthoDeviceId id();
+
+    OrthoDeviceInfo info();
+
+    OrthoDeviceCapabilities capabilities();
+
+    OrthoDeviceState state();
+
+    void connect();
+
+    void disconnect();
+
+    void reset();
+}

ortho-device/src/main/java/org/ortho32/device/OrthoDeviceCapabilities.java

@@ -0,0 +1,14 @@
+package org.ortho32.device;
+
+/**
+ * @param hasTensor whether tensor unit is present
+ * @param hasTrace whether trace buffer is present
+ * @param hasVerify whether verification attest is supported
+ * @param maxScratchpadBytes max tensor scratchpad in bytes
+ */
+public record OrthoDeviceCapabilities(
+        boolean hasTensor,
+        boolean hasTrace,
+        boolean hasVerify,
+        long maxScratchpadBytes
+) {}

ortho-device/src/main/java/org/ortho32/device/OrthoDeviceId.java

@@ -0,0 +1,21 @@
+package org.ortho32.device;
+
+import java.util.Objects;
+
+/**
+ * Stable device identifier.
+ *
+ * @param value stable identifier string
+ */
+public record OrthoDeviceId(String value) {
+
+    public OrthoDeviceId {
+        Objects.requireNonNull(value, "value");
+        if (value.isBlank()) throw new IllegalArgumentException("OrthoDeviceId value must not be blank");
+    }
+
+    @Override
+    public String toString() {
+        return value;
+    }
+}

ortho-device/src/main/java/org/ortho32/device/OrthoDeviceInfo.java

@@ -0,0 +1,23 @@
+package org.ortho32.device;
+
+import java.util.Objects;
+
+/**
+ * @param name human readable name
+ * @param transport transport type (simulator, pcie, usb, ethernet, native)
+ * @param architecture architecture identifier (e.g., ortho-32)
+ * @param firmwareVersion firmware version string
+ */
+public record OrthoDeviceInfo(
+        String name,
+        String transport,
+        String architecture,
+        String firmwareVersion
+) {
+    public OrthoDeviceInfo {
+        Objects.requireNonNull(name);
+        Objects.requireNonNull(transport);
+        Objects.requireNonNull(architecture);
+        Objects.requireNonNull(firmwareVersion);
+    }
+}

ortho-device/src/main/java/org/ortho32/device/OrthoDeviceState.java

@@ -0,0 +1,7 @@
+package org.ortho32.device;
+
+public enum OrthoDeviceState {
+    CONNECTED,
+    DISCONNECTED,
+    ERROR
+}

ortho-fabric/build.gradle.kts

@@ -0,0 +1,7 @@
+plugins {
+    `java-library`
+}
+
+java {
+    toolchain { languageVersion.set(JavaLanguageVersion.of(21)) }
+}

ortho-fabric/src/main/java/org/ortho32/fabric/FabricAddress.java

@@ -0,0 +1,26 @@
+package org.ortho32.fabric;
+
+/**
+ * Typed address in ORTHO-32 memory map.
+ *
+ * @param value 32-bit address value (stored in long to avoid signed issues)
+ */
+public record FabricAddress(long value) {
+
+    public static final FabricAddress SCALAR_RAM = new FabricAddress(0x00000000L);
+    public static final FabricAddress TENSOR_SCRATCHPAD = new FabricAddress(0x10000000L);
+    public static final FabricAddress MMIO = new FabricAddress(0x20000000L);
+    public static final FabricAddress TRACE_BUFFER = new FabricAddress(0x30000000L);
+    public static final FabricAddress HOST_APERTURE = new FabricAddress(0x40000000L);
+
+    public FabricAddress {
+        if (value < 0 || value > 0xFFFFFFFFL) {
+            throw new IllegalArgumentException("FabricAddress out of 32-bit range: " + Long.toHexString(value));
+        }
+    }
+
+    @Override
+    public String toString() {
+        return String.format("0x%08X", value);
+    }
+}

ortho-fabric/src/main/java/org/ortho32/fabric/FabricCommand.java

@@ -0,0 +1,40 @@
+package org.ortho32.fabric;
+
+import org.ortho32.device.OrthoDeviceId;
+import java.util.Objects;
+
+/**
+ * Logical fabric command. Applications never write PCIe BAR registers directly.
+ *
+ * @param opcode operation
+ * @param device target device
+ * @param address typed ORTHO address
+ * @param length length in bytes
+ * @param epoch epoch for deterministic arbitration
+ * @param slot slot in static grant table
+ * @param sequence monotonic sequence number
+ * @param payloadHash SHA-256 hex of payload
+ * @param flags opaque flags
+ */
+public record FabricCommand(
+        FabricOpcode opcode,
+        OrthoDeviceId device,
+        FabricAddress address,
+        int length,
+        FabricEpoch epoch,
+        FabricSlot slot,
+        long sequence,
+        String payloadHash,
+        int flags
+) {
+    public FabricCommand {
+        Objects.requireNonNull(opcode);
+        Objects.requireNonNull(device);
+        Objects.requireNonNull(address);
+        Objects.requireNonNull(epoch);
+        Objects.requireNonNull(slot);
+        Objects.requireNonNull(payloadHash);
+        if (length < 0) throw new IllegalArgumentException("length < 0");
+        if (sequence < 0) throw new IllegalArgumentException("sequence < 0");
+    }
+}

ortho-fabric/src/main/java/org/ortho32/fabric/FabricCompletion.java

@@ -0,0 +1,38 @@
+package org.ortho32.fabric;
+
+import java.util.Objects;
+
+/**
+ * Fabric completion with architectural cycle accounting.
+ * cycles = completionCycle - acceptedCycle. Both are ORTHO architectural cycles, NOT wall-clock milliseconds.
+ *
+ * @param sequence echoed sequence
+ * @param status 0=ok non-zero=error
+ * @param acceptedCycle cycle when fabric accepted the command (long)
+ * @param completionCycle cycle when execution completed (long)
+ * @param resultHash SHA-256 hex of result
+ * @param traceRoot Merkle root / trace hash
+ */
+public record FabricCompletion(
+        long sequence,
+        int status,
+        long acceptedCycle,
+        long completionCycle,
+        String resultHash,
+        String traceRoot
+) {
+    public FabricCompletion {
+        Objects.requireNonNull(resultHash);
+        Objects.requireNonNull(traceRoot);
+        if (completionCycle < acceptedCycle) {
+            throw new IllegalArgumentException("completionCycle < acceptedCycle");
+        }
+    }
+
+    /**
+     * Architectural cycles consumed. Derived, not wall-clock.
+     */
+    public long cycles() {
+        return completionCycle - acceptedCycle;
+    }
+}