The execution contract for governed Operators across runtimes.
Axon provides product-neutral invocation, authority/admission semantics, bounded execution lifecycles and verifiable receipt facts. It is the protocol, canonical Runtime model, native bridge and cross-language SDK foundation used by EasyNet.
EasyNet's product entry is turn a local function into an operation a teammate or agent can call. The first useful result is one real remote invocation. The architecture behind that path is a distributed Operator runtime, described as an Execution Fabric for Heterogeneous Data Environments. Existing catalogs can supply context when the operation acts on data.
For example, generating a Singapore revenue report may require operations over orders, refunds and currency rates held in different systems. The data owner publishes approved business operations; a caller discovers and invokes them without reconstructing every provider's execution interface. Resource access, business definitions and output restrictions remain explicit product concerns.
This is the target product workflow, not a claim that this repository ships a complete data execution product or those integrations today.
Caller / Agent
| discover approved operations (EasyNet product)
v
Operator + concrete resource/provider bindings
| descriptor-bound Invocation (Axon)
v
Runtime admission → provider execution → terminal outcome
→ receipt facts
An Operator is one named, versioned callable operation with a declared input/output contract. SQL, functions, CLI commands, APIs and jobs can supply its implementation. A provider or package can expose multiple Operators. Stateful and stateless implementations are both valid.
Current public APIs still use Ability identifiers. AbilityTarget,
AbilityDescriptor, AbilityDescriptorRef and /ability/ addresses below are
real v1 names. Operator is the new framing; this documentation change does not
introduce a second target kind, rename SDK methods or change signed identities.
See the Operator contract and
migration sequence.
| Layer | Responsibility |
|---|---|
| EasyNet product | Operation discovery, resource bindings, execution policy and outcome views |
| EasyNet Runtime | Product deployment, provider integration, routing and orchestration |
| Axon | Generic addressing, descriptor-bound Invocation, canonical admission/verification, bounded lifecycle and receipt facts |
| Provider | Execute against concrete resources and enforce provider-side access/output constraints |
| Caller or Agent | Choose operations and interpret results using business definitions |
A catalog result is not permission to execute. Admission must validate the exact call under current authority. Resource-bound execution can avoid moving raw datasets into a central engine; outputs, logs and exports still need explicit controls. A signed Receipt attests recorded facts, not arbitrary computation correctness or absence of PII.
| Repository | Role |
|---|---|
| EasyNet-Axon | Protocol, canonical runtime, native bridge and language SDKs |
| EasyNet | Product backend, operation discovery and execution console |
| EasyNet-Cli | Device Runtime, daemon, product SDK, CLI, EAL and integrations |
| EasyRemote | Python callable adaptation, packaging and resident provider host |
EAL remains downstream orchestration that lowers work to child Invocations. Its existing name, syntax and package coordinates are unchanged. Agent planning and memory are outside Axon's execution contract.
Axon defines the current product-neutral contract for resource naming, invocation semantics, content envelopes, signed admission/receipts, terminal states, streaming, and large-payload transfer.
The current wire surface is intentionally small: Invocation exposes
Invoke, InvokeStream, and InvokeBidi; PayloadTransfer exposes
UploadPayload, DownloadPayload, GetPayloadMeta, and DeletePayload.
| Guarantee | Meaning |
|---|---|
| Addressable | Every routable identity has a canonical URA |
| Decidable | Every operation terminates in a known state |
| Provable | Signed admission and terminal outcomes contain verifiable proof facts |
| Resumable | Event replay and configured persistent recovery have explicit bounds; stream-factory reopen does not guarantee exactly-once delivery |
| Bounded | All concurrency knobs are finite; 0 means server maximum, not unbounded |
| URA | Resource | Managed by |
|---|---|---|
easynet:///r/<realm>/agent/<agent-id> |
Runtime identity | Identity |
easynet:///r/<realm>/ability/<ability-id> |
Ability | Descriptor/provider binding |
easynet:///r/<realm>/resource/invocation/<invocation-id> |
Invocation | Invocation |
easynet:///r/<realm>/resource/stream/<session-id> |
Stream session | Stream |
easynet:///r/<realm>/resource/<owner-id>/payload/<payload-id> |
Large payload | PayloadTransfer |
| Mode | Semantics | RPC |
|---|---|---|
SYNC |
Blocking request-response | Invoke |
SERVER_STREAM |
Progressive result chunks | InvokeStream |
BIDI_STREAM |
Bidirectional realtime session | InvokeBidi |
Async submit/watch, batch, and fan-out are not current Axon RPCs. Products may express them as explicit Abilities or caller-side composition.
Axon describes executable work without describing the product that provides it:
| Generic runtime concept | Ownership |
|---|---|
AbilityDescriptor |
Immutable contract identity, schemas, and execution modes owned by Axon. |
| Provider implementation | Runtime-local executable evidence registered behind the descriptor. |
| Provider binding | Explicit association of one descriptor with one implementation inside a runtime. |
BidiSession |
Bounded bidirectional session lifecycle, flow control, cancellation, and terminal closure. |
MCP, A2A, audio, voice, remote control, tool adapters, and product federation
are downstream provider or product capabilities. Their owners translate
product requests into descriptor-bound Invocations and, when needed, register
a provider implementation or consume BidiSession. Canonical Axon SDKs do not export
their product protocol types, lifecycle helpers, catalogs, or presets.
Every protocol-crossing payload (input, output, stream chunk) uses ContentEnvelope with explicit MIME type, encoding, and optional schema.
Large payloads are referenced by PayloadRef (easynet:///r/<realm>/resource/<owner-id>/payload/<payload-id>) and carry full content metadata plus integrity digest.
The current protocol carries signed Invocation material, exact authority bindings, replay/idempotency inputs, signed receipt checkpoints, and content encryption representations. The canonical Runtime owns admission and verification semantics.
EncryptedPayload and ContentEnvelope.encryption describe ciphertext on the
wire. Axon v1 does not currently expose an Identity/session-key negotiation
service; key custody, negotiation, mTLS, and product trust policy are supplied
by the consuming Runtime and deployment. The message schema alone is not an
end-to-end confidentiality guarantee.
| Primitive | Current purpose |
|---|---|
Priority |
Request priority hint carried by Envelope; the host maps it to bounded local policy |
InvocationState |
Accepted -> Admitted -> Dispatched -> Running -> one terminal outcome |
InvocationReceipt |
Signed admission and terminal checkpoints on signed paths |
InvokeStream / InvokeBidi |
Explicit stream direction and terminal closure |
PayloadTransfer |
Chunked upload/download, integrity metadata, and offset resume |
document/- Operator contract, current product framing, concepts, plans, and RFC documents.
core/proto/axon/v1/- Protocol contracts and service definitions.
core/runtime-rs/- Transport-only Rust client and native Dendrite bridge.
sdk/rust/- Canonical
LocalRuntime, admission, receipt, lifecycle, and verifier authority.
- Canonical
sdk/- Language SDK packages (Go/Node/Python/Java/React/Swift).
packaging/- Protocol, SDK, and native transport build and release scripts.
- Root
VERSIONfile holds the current project version coordinate fromtide mark --local-only. packaging/release/sync_versions.showns the existing manifest inventory.- Verify without mutation:
bash packaging/release/sync_versions.sh --check. - Release preparation captures one Tide coordinate and passes it explicitly to
./scripts/update-project-version.sh <version>.
PROJECT_STRUCTURE.md— Repository structure contract, migration rules, and required paths.document/concepts/INVOCATION_STATE_MACHINE.md— Current Invocation state model.document/concepts/INVOCATION_LIFECYCLE_ACROSS_PROCESSES.md— Cross-process lifecycle.- Operator contract — callable operation, binding and evidence boundaries.
- Product framing — data use case, positioning and validation.
- Migration sequence — public API and cross-repository work.
document/rfcs/— Current protocol RFCs and amendments.packaging/release/check_project_structure.sh— Automated project-structure guard for local/CI validation.core/proto/axon/v1/*.proto(generic protocol files):types.proto: core protocol types, addressing, execution semantics, content envelope, state enums.invoke.proto: unary, server-stream, and bidi Invocation plus receipts.transfer.proto: chunked payload upload/download, metadata query, garbage collection.
Product protocols such as voice and remote desktop are owned and versioned by their EasyNet-Cli ability/plugin packages. Axon carries their canonical invocations and receipts without compiling product lifecycle types.
CI builds SDK packs per native target. Release targets:
| Target | Extension | SDK Pack |
|---|---|---|
aarch64-apple-darwin |
.dylib |
sdk-packs-aarch64-apple-darwin.tar.gz |
x86_64-apple-darwin |
.dylib |
sdk-packs-x86_64-apple-darwin.tar.gz |
aarch64-apple-ios |
.a |
sdk-packs-aarch64-apple-ios.tar.gz |
x86_64-apple-ios |
.a |
sdk-packs-x86_64-apple-ios.tar.gz |
x86_64-unknown-linux-gnu |
.so |
sdk-packs-x86_64-unknown-linux-gnu.tar.gz |
aarch64-unknown-linux-gnu |
.so |
sdk-packs-aarch64-unknown-linux-gnu.tar.gz |
aarch64-linux-android |
.so |
sdk-packs-aarch64-linux-android.tar.gz |
x86_64-pc-windows-msvc |
.dll |
sdk-packs-x86_64-pc-windows-msvc.tar.gz |
Each pack contains dist/sdk-packs/<version>/ with language directories (python/, node/, react/, go/, java/, swift/, rust/) plus native/ and runtime/.
Cross-language distribution:
- Python: PyPI hosts all target wheels;
pip installauto-selects platform. - Node/React: npm publishes Linux x86_64; other targets via SDK pack extraction.
- Go:
go get easynet.run/axon/sdk/go; native alignment via SDK pack. - Java: Maven Central source artifact; target-native via SDK pack.
- Swift: SPM from tag (macOS); iOS via
aarch64-apple-ios/x86_64-apple-iospack. - Rust: target-compiled in consumer build;
EASYNET_DENDRITE_BRIDGE_LIBfor explicit path injection.
Environment variables for cross-target/CI workflows:
SDK_TARGET,SDK_LIB_EXT,SKIP_NATIVE_BUILD,SDK_VERSIONEASYNET_DENDRITE_BRIDGE_PLATFORM=ios|android|linux|windows|macosEASYNET_DENDRITE_BRIDGE_LIB=/abs/path/to/libaxon_dendrite_bridge.*EASYNET_DENDRITE_BRIDGE_HOME=<pack-root>EASYNET_DENDRITE_BRIDGE_SOURCE=local
The base Dendrite Bridge surface is available in all six language SDKs.
Node heartbeat renewal is no longer an SDK-owned node_agent loop:
membership lifecycle belongs to the runtime/control plane, while SDKs
own transport reconnect helpers and stream-factory retry wrappers.
| Surface | Rust | Python | Go | Node | Java | Swift |
|---|---|---|---|---|---|---|
| Dendrite Bridge | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Automatic bridge reconnect driver | ✅ | ✅ | ✅ | ✅ | Not provided | Not provided |
stream_resume (stream factory w/ transparent reopen) |
✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
See the stream reopen evidence and test commands for implementation links, executed coverage and limits of this support table.
Java and Swift expose transport-error classification and backoff utilities for caller-owned reconnect loops; their options do not start an automatic bridge worker. Their stream wrappers independently reopen a caller-supplied source factory. See reconnect and stream evidence for implementation links and the scope of executed tests.
Contract for SDKs with automatic bridge reconnect drivers:
- Reconnect backoff is bounded and monotonic; language facades expose explicit caps instead of unbounded retry loops.
- Reconnect hooks run after the bridge is reopened so callers can re-register application resources without owning node membership.
- Transport-looking failures trigger reconnect; validation and policy errors are returned unchanged.
stream_resume currently documents that exactly-once delivery across a
reconnect is not guaranteed — reconnected streams restart from the
factory, so consumers must layer idempotency keys at the downstream provider
call site.
LocalRuntimeadmission, replay/idempotency, provider registration, lifecycle, receipts, and verification semantics insdk/rust/.- Unary
Invoke, server-streamInvokeStream, and bidiInvokeBidi. - Explicit child-invocation causality and receipt anchors in the canonical model.
- Large-payload upload/download, metadata, deletion, and offset resume.
- Native Dendrite bridge plus cross-language SDK and conformance surfaces.
Product integrations, including MCP, A2A, audio/voice, remote control, tool adapters, and federation membership or discovery APIs, are not Axon delivery surfaces. They are implemented and versioned by downstream providers and products over the generic runtime model above.
Apache-2.0 — see LICENSE.
This repository is a deliberately bounded public release of the wider EasyNet research system. See Public Source Release Scope for what is published, what remains outside the distribution, and why releases are staged.