Concepts
Architecture, policy model, agent profiles, and the plugin contract.
Featherlane AI is a runtime safety layer for production agents. The important moment is the boundary before an agent speaks, sends, writes, or takes another externally visible action.
Core Ideas
| Concept | Meaning |
|---|---|
| Check | One request asking whether a proposed output is safe to deliver. |
| Authorization decision | The typed response from Featherlane AI. It includes the effect, reason, findings, latency, trace id, and durable authority references when applicable. |
| Authorization effect | One of permit, deny, transform, require_approval, or defer. Approval can satisfy only require_approval; it cannot bypass deny or defer. |
| Policy | A YAML rule that scopes when it applies, what it matches, and which action to take. |
| Agent profile | Context about the agent's domain, authority, tone, and constraints. |
| Trace | The persisted record that lets operators inspect what happened later. |
Approval And Execution Flow
| Term | Plain-language meaning |
|---|---|
| Intent | The durable record of the action the agent is proposing. It is not permission to execute. |
| Approval | A pending human decision. Approving creates authority but does not execute the action. |
| Grant | Revocable authority for one exact action or a bounded reusable scope. It never overrides current policy. |
| Authorization claim | The grant and attempt identifiers the caller presents when retrying the action. |
| Lease | A one-attempt execution right issued only after Featherlane AI rechecks current policy and live state. |
| Authorization receipt | Audit evidence explaining the decision and linking its intent, approval, grant, and lease. It carries no execution rights. |
The complete flow is:
- The agent proposes an executable action and Featherlane AI records its intent.
- Policies and live checks evaluate the action.
- If authority is missing, one domain-labeled item appears in Approvals.
- Approval creates an exact-once or bounded scoped grant.
- The caller retries with that grant; Featherlane AI rechecks current policy and live state.
- A one-attempt lease prevents duplicate execution.
- Featherlane AI writes an authorization receipt, while the domain records its own result.
Financial actions use this same approval flow. Approvals is the only place a person approves or denies them; Financial actions remains the ledger and execution-history view.
Runtime Shape
The Rust backend is the source of truth. SDKs call the Rust server directly for
runtime decisions, especially POST /v1/events. The web dashboard may proxy and
display data, but it does not own policy evaluation or trace storage.
Latency Model
Featherlane AI is designed around channel budgets:
| Channel | Target |
|---|---|
| Streaming chat | deterministic checks under the realtime budget |
| Chat | synchronous guardrail decisions before the message is shown |
| Email and jobs | slower checks are acceptable because delivery is asynchronous |
| Replay | offline analysis can spend more time for richer evaluation |
The hot path starts with deterministic policies because that is the only layer that can be consistently fast enough for realtime streaming.
Source Of Truth
The deeper concept docs live in docs/concept/ in the repo:
architecture.mdexplains request flow and ownership.crates.mdexplains each Rust crate and dependency boundary.glossary.mddefines domain terms once.plugin-contract.mddescribes extension boundaries.v0-design-decisions.mdrecords why the current runtime shape exists.
Diagram source lives in docs/diagrams/*.d2; run pnpm docs:diagrams to
regenerate the SVGs used by this site and the repo Markdown docs.