This file is the operating manual for agents working in EasyNet-Axon. Axon is the product-neutral protocol, canonical runtime model, native Dendrite bridge, and cross-language SDK contract consumed by EasyNet Runtime and downstream facades.
- Read this file,
AGENTS.md,PROJECT_STRUCTURE.md, and the closest protocol or SDK contract before editing. - Run
git status --shorthere and in consuming repositories. Preserve unrelated changes and generated evidence; stage explicit paths only. - Create or update
pr/<date>-<task>/with intent, invariants, architecture, API contract, execution checklist, verification, and decisions. - Determine whether the change belongs to protocol, canonical Rust semantics, native transport, a language facade, or downstream product code.
- Implement from the lowest owning layer upward and prove failure/recovery paths before performance or ergonomics work.
| Layer | Canonical location | Responsibility |
|---|---|---|
| Wire protocol | core/proto/axon/v1/ |
messages, services, canonical wire vocabulary |
| URA primitive | core/ura-rs/ |
parsing, canonicalization, builders |
| Transport client | core/runtime-rs/client-sdk/ |
low-level protocol transport only |
| Native bridge | core/runtime-rs/dendrite-bridge/ |
C ABI transport/projection boundary |
| Canonical semantics | sdk/rust/ |
LocalRuntime, admission, verification, lifecycle |
| Language SDKs | sdk/{python,node,react,go,java,swift}/ |
equivalent public facades |
| Conformance truth | sdk/conformance/ |
cross-language facts and parity gates |
| Packaging/release | packaging/, scripts/, .github/workflows/ |
reproducible artifacts and publication |
Axon owns canonical URAs, descriptor-bound Invocation, authority/signature facts, admission, replay/idempotency, receipts, stream/bidi lifecycle, terminal semantics, and protocol errors. It does not own EasyNet pairing UI, federation product policy, plugins, Mission/EAL, remote desktop, voice, MCP, or EasyRemote decorators. Those remain downstream providers/products that translate into generic Axon contracts.
Every register, heartbeat, publish, install, activate, invoke, stream, and bidi path must prove:
- a deterministic terminal state;
- queryable, replay-safe idempotency;
- crash/restart recovery for locks and guards;
- hard bounds for concurrency, buffers, retries, and queueing;
- one traceable lifecycle and one terminal closure per stream/session;
- structural tenant isolation and exact authority/signature binding.
Do not add product-specific shortcuts, legacy fallback paths, sentinel identity values, permissive unknown-field handling, or default-unbounded behavior.
Axon is not the user-facing EasyNet daemon. EasyNet-Cli embeds/consumes Axon and
owns easynet runtime start. Do not instruct EasyRemote users to launch a
standalone Axon process.
Use repository-local verification instead:
bash packaging/release/check_project_structure.sh
cd core/runtime-rs/client-sdk
cargo test --locked -- --test-threads=1
cd ../dendrite-bridge
cargo test --locked
cd ../../../sdk/python
uv sync --extra dev
uv run pytest -q testsNative Python/other SDK tests may require a built Dendrite bridge and an exact
EASYNET_DENDRITE_BRIDGE_LIB path. Follow .github/workflows/ci.yml for target
setup rather than inventing a development-path fallback in production loaders.
Axon has one release coordinate across Rust crates, Python, Node/React, Java,
Go-facing release metadata, examples, and existing locks. Root VERSION is the
committed source of truth; packaging/release/sync_versions.sh owns the complete
manifest inventory.
Never edit individual manifests as a release strategy. Use:
# after functional code freeze
AXON_VERSION="$(tide mark --local-only)"
./scripts/update-project-version.sh "$AXON_VERSION"
./scripts/update-project-version.sh --check "$AXON_VERSION"./scripts/bump-version.sh --dry-run previews convergence, and
./scripts/bump-version.sh [VERSION] delegates to the transactional project
updater. The updater regenerates every existing Cargo, npm, and uv lock, writes
VERSION only after successful synchronization, and verifies the final state.
Tide resolves the functional HEAD, so release preparation must be serialized:
- Freeze functional changes.
- Capture the Tide value exactly once.
- Synchronize with that explicit value.
- Commit only version and generated release metadata.
- Tag that commit as
v<VERSION>using the captured value. Do not recompute Tide after the metadata commit or after another functional commit lands.
.github/workflows/release.yml is validation-only on manual dispatch. An exact
v<VERSION> tag builds native targets and SDK packs, creates the GitHub release,
and publishes configured language registries. Never create/push a tag or run an
external publication without explicit authorization.
Downstream release order is Axon first, then EasyNet easynet-sdk and Runtime,
then EasyRemote. Downstream registry-only resolution must pass before its tag.
For a reviewable release branch, the repository-owned transaction composes the same synchronizer and contract generator in an isolated worktree:
git switch -c release/axon-v"$(tide mark --local-only)"
python3 scripts/release-coordinate.py --check
python3 scripts/release-coordinate.py --push--commit stops after fast-forwarding the local branch. --push performs a
non-force push and refuses main/master; if the network push fails after the
metadata commit is created, retry only the external step with --push-only.
Neither mode tags or publishes artifacts.
- Change
.protoonly when wire semantics truly change. Regenerate all checked outputs and update every language projection/conformance fact in the same capability sequence. - Put canonical admission, verification, lifecycle, receipt, and terminal
behavior in
sdk/rust/; language SDKs adapt that model rather than inventing local semantics. - Keep the Dendrite bridge transport-only. Additive ABI features are feature-detected; do not silently change the base ABI contract or bind native symbols directly in downstream facades.
- Use explicit state types and narrow interfaces. Eliminate duplicated policy across unary, stream, bidi, local, and forwarded paths.
- Remove obsolete code after migration. Compatibility exists only when a current specification requires it.
- Maintain contract headers in core Rust and major runtime modules: file and description, protocol responsibility, implementation approach, usage contract, and architectural position.
Release, code-generation, migration, and conformance scripts must:
- use strict error handling and resolve root paths from
BASH_SOURCE; - inventory targets centrally and deterministically, excluding generated, dependency, and VCS directories explicitly;
- validate the complete input and version before any mutation;
- offer
--check/--dry-runand make it provably read-only; - update coupled manifests and locks transactionally, rolling back on failure;
- write the root source of truth only after all generated state succeeds;
- avoid
rgin bootstrap/release mutation paths when portable POSIX tools are sufficient; developer/conformance diagnostics may requirergexplicitly; - never warn-and-continue after a required generator, package manager, or lock operation fails;
- quote paths, use arrays for target sets, bound subprocess/retry behavior, and avoid ambiguous globs;
- emit concise, auditable output without keys, tokens, credentials, signatures, or authority headers;
- include focused tests for malformed input, drift detection, target isolation, partial failure, rollback, and idempotent reruns.
Start focused, then run all affected language and packaging gates:
bash packaging/release/check_project_structure.sh
bash packaging/release/sync_versions.sh --check
(cd core/runtime-rs/client-sdk && cargo test --locked -- --test-threads=1)
(cd core/runtime-rs/dendrite-bridge && cargo test --locked)
(cd sdk/python && uv run pytest -q tests)
(cd sdk/go && go test ./...)
(cd sdk/node && npm run verify)
(cd sdk/react && npm test)
(cd sdk/java && mvn -q test)Use .github/workflows/ci.yml as the complete platform/language matrix and
.github/workflows/release.yml as the artifact contract. Record skipped targets
and toolchain limitations explicitly; never generalize one-platform success to
the full release matrix.
Split commits in dependency order: protocol/core, canonical SDK semantics,
language facades, then packaging/docs. Stage explicit files in dirty trees.
Commit only as Silan.Hu <silan.hu@u.nus.edu> with no co-author trailers. Do
not tag, push, publish, or dispatch external workflows without explicit user
authorization.