Architecture

The canonical architecture document lives in docs/development/architecture.md.

It covers package dependency direction, runtime request flow, JSON-RPC dispatch, task lifecycle, storage, registry polling, outbound URL policy, auth, telemetry, release flow, and the tests and ADRs that protect those decisions.

Package Direction

types/schemas -> core runtime -> transports -> client/registry -> adapters/bridges -> CLI/apps

packages/runtime owns protocol types, schemas, runtime, client primitives, storage, and outbound network policy. Auth and telemetry live in separate packages (packages/auth, packages/telemetry) and are re-exported through packages/runtime. Transports, registry, adapters, bridges, CLI, apps, docs-site, and examples consume public package APIs above that layer.

Workspace graph

Run the graph check when package boundaries change:

node scripts/check-workspace-graph.mjs --summary

Expected summary:

Workspace graph validation passed.
Checked 8 public package import aliases across 36 forbidden dependency edges.
Dependency direction: types/schemas -> core runtime -> transports -> registry -> adapters/bridges -> CLI/apps.

Verification Links

• ADR index
• Client/server integration tests
• Transport contract helper
• Task lifecycle property tests
• Telemetry snapshot tests
• Release artifact tests