Aileron Docs

Architecture Decisions

This section holds the architecture decision records (ADRs) that define Aileron’s architecture. Each ADR captures one decision: the context, the choice, the trade-offs, and the consequences.

What’s landed

  • ADR-0001: Manifest Format Conventions — Markdown body + TOML frontmatter for actions; pure TOML for connectors and project config; JSON for runtime IPC.
  • ADR-0002: Connector Model — Connectors are sandboxed, content-addressed binaries; Aileron core ships only primitive capability types.
  • ADR-0003: Action Model — Atomic actions copied into the user’s ~/.aileron/actions/ on install; depend on connectors with explicit version + hash + capability subsets; capability enforcement at the action boundary in addition to the connector boundary. v1 is user-level only.
  • ADR-0004: Dependency Resolution — Per-scheme FQN-to-fetch-URL mapping (Go modules tag conventions); content-addressed shared store; install/sync/check pipelines; offline-by-default after first install.
  • ADR-0005: Sandbox Choice — WASM Component Model is the connector sandbox; runtime mediates credential use so connectors never hold raw credentials. Non-WASM-capable connectors are out of scope for v1.
  • ADR-0006: Capability Binding UX — Bindings are explicit user acts; install-time transparency, first-use binding, opt-in pre-binding; bindings are user-local, never project-committable; visible lifecycle commands (list/inspect/setup/rebind/revoke).
  • ADR-0007: Install Consent Flow — Install is a single binary decision (install or cancel); no per-capability denial; signature failure is a hard fail; updates show capability diffs; headless mode requires explicit --yes per command.
  • ADR-0008: Intent Matching Mechanisms — Tool augmentation via function calling is the intent-matching mechanism; agent-defined tools take precedence in name collisions.
  • ADR-0009: User Channel and OOB Approval Surfaces — In-band streaming output describes; out-of-band surfaces decide. The agent is structurally never in the trust path for approvals. v1 MVP ships with CLI prompt only; web UI, system notifications, biometric, and a hosted Aileron backend are Phase 2.
  • ADR-0010: Failure-Handling Policy — Failures are visible and structured; closed-set failure-class taxonomy; idempotency is the default; bounded retry on retriable errors; v1 actions are linear with first-failure-terminates semantics. LLM fallback, conditional compensation, and per-call retry tuning are post-MVP enhancements.
  • ADR-0011: Local Credential Vault — Encrypted-at-rest local vault for user credentials. Argon2id KDF from a passphrase derives a key encryption key (KEK); AES-256-GCM envelope encryption protects bindings on disk. KEK held in memory for the runtime session, never persisted. TEE-backed and browser-enclave variants exist in code but are post-MVP.

The sequence

The eleven ADRs form a complete architectural ratification of Aileron’s v1, tracked in issue #343:

  1. Manifest Format Conventions — landed (ADR-0001)
  2. Connector Model — landed (ADR-0002)
  3. Action Model — landed (ADR-0003)
  4. Dependency Resolution — landed (ADR-0004)
  5. Sandbox Choice — landed (ADR-0005)
  6. Capability Binding UX — landed (ADR-0006)
  7. Install Consent Flow — landed (ADR-0007)
  8. Intent Matching Mechanisms — landed (ADR-0008)
  9. User Channel and OOB Approval Surfaces — landed (ADR-0009)
  10. Failure-Handling Policy — landed (ADR-0010)
  11. Local Credential Vault — landed (ADR-0011)

Aileron is user-level by construction in v1 — actions live in ~/.aileron/actions/, not in the project’s repo. Project-level shared actions, team-coordination features, and the TEE / browser-enclave vault variants are post-MVP, deferred until the hosted backend ships.

How to read these

  • Each ADR is a decision, not a design document. Operational detail is included where it ratifies the decision; broader implementation detail belongs in code and PRs.
  • ADRs are editable until the first working MVP ships. Real usage will surface assumptions worth revising; until MVP, an ADR is amended in place when its decision changes. Once MVP ships, this section will switch to the standard immutability convention: superseding decisions land as new ADRs that explicitly cite what they replace.