WAIT — Missing license — unclear to depend on

• Last commit today
• 6 active contributors
• Distributed ownership (top contributor 32% of recent commits)
• CI configured
• Tests present
• ⚠ No license — legally unclear to depend on

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

iii is a distributed service orchestration platform that collapses multi-service architectures into three primitives: Workers (processes registering functions), Triggers (declarative event sources), and Functions (units of work). It eliminates service integration complexity by providing a unified runtime where any language (Rust, TypeScript, Python, etc.) can register capabilities once and interoperate seamlessly with every other service in the system. Workspace monorepo: engine/ contains the core ELv2-licensed runtime, sdk/packages/rust/iii is the Rust SDK, crates/ houses tooling (iii-init, iii-supervisor, iii-shell-client, iii-worker, scaffolder-core), console/packages/console-rust provides observability UX, and blog/ is Astro-based documentation. .github/scripts/ (build_engine_publish_payload.py, collect_engine_worker_interface.py) automate cross-language worker interface generation.

Backend engineers and platform teams building polyglot microservices who want to reduce integration boilerplate; AI agents and LLM-based automation systems that need reliable introspection of system capabilities; DevOps teams managing heterogeneous service meshes where services span multiple languages and runtimes.

Actively developed with a clear release cadence (version 0.11.7-next.1 in Cargo.toml), comprehensive CI/CD pipelines in .github/workflows/ (ci.yml, release-iii.yml, docker-engine.yml), and multi-language SDK support (Rust, TypeScript, Python, npm, PyPI, crates.io). The dual licensing model (ELv2 for engine, Apache-2.0 for SDK) and presence of CONTRIBUTING.md and pull request templates indicate production intent, though the 0.x version suggests API stabilization is ongoing.

The monorepo spans 5.9M Rust LOC, 1.2M TypeScript, and 479k Python with 16 workspace members (Cargo.toml), creating significant coordination risk across language boundaries. The engine uses proprietary ELv2 licensing while SDKs are Apache-2.0, which may create friction for certain use cases. No visible test coverage metrics in the file list; reliance on the single engine crate as the coordination point creates a potential bottleneck.

Active development with multi-language SDK maturation (npm, PyPI, crates.io packages published), website/documentation deployment automation (.github/workflows/deploy-website.yml, generate-api-docs.yml), engine worker publishing pipeline (_publish-engine-workers.yml), and benchmarking infrastructure (bench-release.yml). The presence of cloudfront-functions-test.yml and terraform planning workflows (tf-plan.yml) indicates expansion of deployment targets.

Clone and bootstrap: git clone https://github.com/iii-hq/iii.git && cd iii && cargo build. The workspace uses Rust's resolver = "2" (Cargo.toml) and includes a Makefile. Install git hooks: .githooks/pre-commit. For TypeScript/Python SDKs, navigate to sdk/packages/rust/iii or language-specific directories and follow language-specific setup (npm/pip/cargo).

Daily commands: Start the engine: cargo build -p iii then ./target/debug/iii (or release binary). For SDK examples, navigate to sdk/packages/rust/iii-example and run cargo run. The Makefile contains convenience targets; inspect it with make help or cat Makefile. Console observability UI runs separately; see console/packages/console-rust for setup.

• Cargo.toml — Root workspace configuration defining all member crates, dependencies, and the version (0.11.7-next.1) that must be updated during releases.
• engine/Cargo.toml — Engine crate root—iii's core orchestration runtime that coordinates all services and workers; foundational to the entire system.
• sdk/packages/rust/iii/lib.rs — Rust SDK entry point that developers use to create workers; defines the public API surface for service composition.
• .github/workflows/release-iii.yml — Release automation pipeline for publishing Docker images, npm, PyPI, and Crates.io packages across all SDKs.
• console/packages/console-frontend/index.html — Console UI entry point for real-time service observation and management; primary user-facing dashboard.
• crates/iii-worker/lib.rs — Worker abstraction layer managing lifecycle, registration, and inter-service communication for all registered services.
• crates/iii-network/lib.rs — Network orchestration layer handling service discovery, message routing, and inter-worker RPC calls.

Add a New Worker Service

1. Generate new worker project scaffold using iii init command (crates/iii-init/lib.rs)
2. Define worker functions using #[iii::function] macro from engine/function-macros (engine/function-macros/lib.rs)
3. Register worker with engine by implementing Worker trait and calling engine.register() (crates/iii-worker/lib.rs)
4. Export via SDK (Rust, Node.js, or Python) using appropriate language binding (sdk/packages/rust/iii)

Add a New Console UI Feature

1. Create new React/Astro component in console-frontend following DESIGN.md patterns (console/packages/console-frontend/DESIGN.md)
2. Add corresponding API endpoint in console-rust backend service (console/packages/console-rust/Cargo.toml)
3. Wire WebSocket event subscription for real-time updates via network orchestration layer (crates/iii-network/lib.rs)
4. Update biome.json if new linting rules needed for TypeScript/JSX (biome.json)

Add Support for New Language SDK

1. Create new SDK package directory under sdk/packages/<language>/ (sdk/packages/rust/iii)
2. Generate FFI bindings or language-specific wrapper around engine protocol (crates/iii-shell-proto/lib.rs)
3. Add new publish workflow in .github/workflows/_<language>.yml for CI/CD (.github/workflows/_npm.yml)
4. Register new package in release-iii.yml and build_engine_publish_payload.py for distribution (.github/scripts/build_engine_publish_payload.py)

Release a New Version

1. Update version field in Cargo.toml workspace package (e.g., 0.11.7-next.1) (Cargo.toml)
2. Push tag to main branch; GitHub Actions will automatically trigger release-iii.yml workflow (.github/workflows/release-iii.yml)
3. Workflow builds Docker image, publishes to npm/PyPI/Crates.io using credentials in GitHub Secrets (.github/scripts/build_engine_publish_payload.py)
4. Verify artifacts appear on Docker Hub, npm, PyPI, and Crates.io package registries (.github/workflows/_homebrew.yml)

• Rust (engine, core crates, worker runtime) — High-performance zero-copy orchestration, memory safety without GC, async/await for I/O multiplexing across thousands of workers.
• Tokio async runtime — Enables efficient event-driven architecture handling many concurrent worker connections and inter-service RPC calls.
• Multi-language SDKs (Rust, JavaScript, Python) — Developers write workers in their preferred language while engine handles orchestration; broad ecosystem adoption.
• React/Astro console frontend — Real-time WebSocket-driven UI for composing and observing services; modern component model for complex dashboards.
• Procedural macros (#[iii::function]) — Zero boilerplate: macros auto-generate registration, serialization, and tracing code for worker functions.
• Docker containerization — Portable engine deployment across cloud providers and local development; versioned binary distribution.

• Single orchestration engine (not distributed consensus)

  • Why: Simplicity and deterministic routing—every service can reach every other service without gossip or leader election overhead.
  • Consequence: Engine becomes single point of coordination; horizontal scaling requires multiple independent engine instances (not yet auto-sharded).

• Protocol-first SDK generation via macros and code generation

  • Why: Eliminates manual IDL maintenance and RPC boilerplate; developers focus on business logic.
  • Consequence: Macro errors can be cryptic; tight coupling between engine schema and SDK codegen—breaking changes require coordinated releases.

• Real-time console observations via streaming WebSocket, not polling

  • Why: Sub-second latency for live execution traces and metrics; efficient for many concurrent observers.
  • Consequence: Console requires persistent connection; scaling console backend requires stateful session management.

• No built-in authentication/authorization in core engine

  • Why: Engine is orchestration-layer abstraction; security delegated to deployment (firewalls, container isolation, TLS termination).
  • Consequence: Must be deployed behind API

The workspace uses edition = "2024" (non-standard; likely typo for 2021) in Cargo.toml—verify MSRV requirements. ELv2 engine licensing is incompatible with GPL; integrators must use SDK-only approach for GPL projects. The monorepo requires all members to compile together; partial builds may fail. Pre-commit hooks (.githooks/pre-commit) are installed by contributors manually—ensure they run before pushing. Cross-language worker interface collection (.github/scripts/) runs during CI; local development may require manual regeneration if you modify function signatures. The console-rust observability UI is a separate startup; engine won't provide visibility without it running.

• Worker Pattern — The foundational abstraction in iii; understanding how processes register with the engine and expose capabilities is essential to architecting polyglot systems
• Declarative Trigger Routing — Unlike explicit message queue subscriptions, iii's trigger model is declarative ("this function runs when X happens"), reducing coupling and enabling automatic schema validation; critical for understanding how events flow
• Polyglot Service Mesh — iii's core value is language-agnostic interop without boilerplate; requires understanding how function signatures, serialization, and discovery work across Rust, TypeScript, Python boundaries
• Proc Macros (Rust) — The function-macros crate uses Rust procedural macros to annotate functions for iii registration; understanding macro expansion is key to modifying Function definition semantics
• Zero-Copy Serialization (serde) — iii uses serde for Function input/output serialization across service boundaries; efficient serialization directly impacts latency of inter-service calls
• Async Runtime Coordination (tokio) — The engine is built on tokio's multi-threaded runtime; understanding task spawning and channel-based communication is required for debugging trigger dispatch and function invocation
• Dual Licensing (ELv2 + Apache-2.0) — Engine is proprietary (ELv2) while SDKs are open (Apache-2.0); understanding the license boundary affects how integrators can modify and distribute their code

• temporalio/temporal — Workflow orchestration engine solving similar distributed coordination problem but focused on long-running processes and deterministic execution rather than polyglot service interop
• apache/kafka — Event streaming backbone often used alongside iii for Trigger implementation; complements iii's declarative routing with durable event storage
• grpc/grpc — Alternative RPC framework for service-to-service communication; iii abstracts away the transport layer whereas gRPC requires explicit stub generation per service pair
• open-telemetry/opentelemetry — Observability framework that integrates with iii's console-rust for distributed tracing and metrics collection across Workers
• iii-hq/iii-examples — Companion repository containing runnable end-to-end examples using iii engine with multi-language workers (if it exists; based on monorepo pattern)

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for multi-language SDK initialization across Rust, Python, and Node.js

The repo has SDKs in three languages (Rust in sdk/packages/rust/iii, Python in PyPI, Node.js in npm) but the test structure (config/nextest.toml shows Rust testing setup) doesn't show cross-language integration tests. Given the complexity of service composition in iii, adding tests that verify SDKs can initialize and communicate with the engine would catch breaking changes early and improve confidence in polyglot deployments.

• [ ] Review existing Rust SDK tests in sdk/packages/rust/iii and iii-example
• [ ] Create .github/workflows/sdk-integration-tests.yml to run parallel tests for all three SDK languages
• [ ] Add integration test cases in crates/iii-worker to verify engine-worker protocol compatibility across language bindings
• [ ] Document test execution in CONTRIBUTING.md with language-specific setup instructions

Implement CI workflow for Python and Node.js SDK publishing validation

The repo has _py.yml, _npm.yml, and _rust-cargo.yml workflows but no visible validation that published SDK versions match workspace version (0.11.7-next.1). This creates risk of version skew across package managers. A dedicated workflow should validate package.json, setup.py, and Cargo.toml all declare the same version before publication.

• [ ] Create .github/workflows/validate-sdk-versions.yml that runs on PR and main
• [ ] Add script in .github/scripts to parse versions from sdk/packages/rust/iii/Cargo.toml, blog/package.json (or appropriate Python setup.py location), and blog/package.json
• [ ] Fail the workflow if versions don't match workspace.package.version from root Cargo.toml
• [ ] Document in CONTRIBUTING.md how to bump versions consistently across all SDKs

Add documentation for the engine worker protocol used by crates/iii-worker and crates/iii-shell-proto

The file structure shows crates/iii-shell-proto and crates/iii-worker exist, suggesting a worker communication protocol, but there's no visible protocol documentation (no .proto files listed, no PROTOCOL.md). New contributors need to understand how workers register, accept tasks, and report results. This is critical for anyone adding new worker types or language bindings.

• [ ] Review crates/iii-shell-proto/src and crates/iii-worker/src to extract protocol messages and behavior
• [ ] Create docs/WORKER_PROTOCOL.md documenting message types, state machines, and error handling
• [ ] Add examples in docs/WORKER_PROTOCOL.md showing how to implement a worker in a new language
• [ ] Link WORKER_PROTOCOL.md from CONTRIBUTING.md and README.md under architecture/extending sections

• Add integration tests for cross-language function calls: create tests/cross_language/ with Rust, TypeScript, and Python workers calling each other's functions to ensure serialization and trigger routing work end-to-end.
• Document worker registration lifecycle in CONTRIBUTING.md: trace a Function from declaration (function-macros) through registration (iii-supervisor) to dispatch (engine) with code examples, filling the gap between README's high-level concepts and crate-level implementation.
• Implement missing SDK examples: sdk/packages/rust/iii-example only shows one pattern; add examples for HTTP triggers, cron scheduling, and state change subscriptions to match the three primitive claims in the README.

The codebase demonstrates a reasonable security baseline with multi-layered architecture and proper use of memory-safe Rust. However, there are opportunities for improvement: (1) Dependency versions should be more tightly pinned to prevent unexpected vulnerable package installations, (2) Automated security scanning for dependencies is not evident in the CI/CD pipeline and should be added, (3) TLS configuration should be explicitly verified across all HTTP clients. The monorepo structure with workspace management is well-organized, and the presence of security-focused CI workflows (license checks, etc.) is positive. No hardcoded secrets, injection vulnerabilities, or obvious misconfigurations were identified in the provided file structure.

• Medium · Outdated Tokio Dependency Version — Cargo.toml - workspace.dependencies. The workspace uses tokio version '1' without specifying a minimum patch version. This could allow installation of older tokio versions that may contain known security vulnerabilities. The dependency specification should use a caret requirement to ensure security patches are included. Fix: Update tokio dependency to specify a minimum safe version: tokio = { version = "1.40", ... } or later, and enable automatic security updates through dependabot or similar tools.
• Medium · Permissive Reqwest TLS Configuration — Cargo.toml - workspace.dependencies. The reqwest dependency is configured with 'rustls-tls' feature but the version constraint '0.12' is not pinned. Additionally, no explicit verification of certificate validation settings is visible in the dependency declaration. Fix: Pin the reqwest version to a known-safe release and verify that certificate validation is enabled in all HTTP client instantiations. Review code for proper TLS configuration.
• Medium · Missing Dependency Security Scanning — .github/workflows/ - CI configuration. No evidence of automated security scanning tools (cargo-audit, cargo-deny) in the CI/CD workflows based on the provided file structure. This increases the risk of undetected vulnerable dependencies. Fix: Integrate cargo-audit or cargo-deny into the CI/CD pipeline to automatically scan for known vulnerabilities in dependencies. Add this to the ci.yml workflow.
• Low · Unencrypted Dependencies Over HTTP Potential — Cargo.toml and Cargo.lock. The Cargo.lock file is present but dependency sources are not explicitly constrained to use HTTPS. While Cargo defaults to HTTPS, explicit configuration would improve security posture. Fix: Ensure all crate registries use HTTPS-only sources. Consider adding a .cargo/config.toml override to enforce strict registry policies.
• Low · Loose UUID Dependency Version — Cargo.toml - workspace.dependencies. The uuid dependency uses version '1' without a minimum patch version constraint, potentially allowing installation of earlier patch versions that may have minor security or stability issues. Fix: Pin uuid to a specific minimum version: uuid = { version = "1.10", ... } or later.
• Low · License Compliance Automation Present — .github/scripts/license-agreement-check.mjs. While a license-agreement-check.mjs script exists, it's unclear if all dependencies are being checked against approved licenses. Open source license compliance can pose legal security risks. Fix: Verify that the license check script covers all workspace members and transitive dependencies. Consider using tools like cargo-license or SPDX tooling for comprehensive compliance.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/iii-hq/iii shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live iii-hq/iii repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/iii-hq/iii.

What it runs against: a local clone of iii-hq/iii — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in iii-hq/iii | Confirms the artifact applies here, not a fork | | 2 | Default branch main exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of iii-hq/iii. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/iii-hq/iii.git
#   cd iii
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of iii-hq/iii and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "iii-hq/iii(\\.git)?\\b" \\
  && ok "origin remote is iii-hq/iii" \\
  || miss "origin remote is not iii-hq/iii (artifact may be from a fork)"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "engine/Cargo.toml" \\
  && ok "engine/Cargo.toml" \\
  || miss "missing critical file: engine/Cargo.toml"
test -f "sdk/packages/rust/iii/lib.rs" \\
  && ok "sdk/packages/rust/iii/lib.rs" \\
  || miss "missing critical file: sdk/packages/rust/iii/lib.rs"
test -f ".github/workflows/release-iii.yml" \\
  && ok ".github/workflows/release-iii.yml" \\
  || miss "missing critical file: .github/workflows/release-iii.yml"
test -f "console/packages/console-frontend/index.html" \\
  && ok "console/packages/console-frontend/index.html" \\
  || miss "missing critical file: console/packages/console-frontend/index.html"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/iii-hq/iii"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.