Architecture Glossary

Plain-English definitions for terms and concepts used across this documentation site. Each entry explains what the concept means, why it matters, and where it is applied in practice.

Core Architecture Concepts

Shared Understanding

The session's live digital notepad. It captures the customer's intent (occasion, recipient relationship, budget, card message) in a structured format that both the shopper and store services can read and update in real time.

• Why it matters: It gives the AI persistent context without having to stuff raw chat transcripts into every prompt.
• Where to see it: Explored on the Framework Home and Schema.

Domain Services

The authoritative backend software systems that manage real-world business operations: inventory, pricing, delivery scheduling, payment, and order management.

• Why it matters: AI language models are probabilistic word predictors; they cannot reliably track warehouse stock. Domain services always decide transactions.
• Where to see it: Diagrammed on the System Stack.

Outer Harness

The software factory and automated safety scaffolding built around conversational AI to ensure honesty, reliability, and security in production. It consists of six layers: Guides, Sensors, Loop, Memory, Permissions, and Observability.

• Why it matters: Without an outer harness, AI prototypes hallucinate prices, leak data, or break when edge cases arise.
• Where to see it: Detailed on the Comparison & Visual Guide.

Fail-Closed Availability

A safety design rule: if a backend service (such as cooler inventory or delivery driver scheduling) is unreachable or times out, the purchase action turns off immediately.

• Why it matters: It is far better to display "Checking inventory..." than to accept a customer's money for flowers that cannot be delivered.
• Where to see it: Referenced in the Comparison.

Thin Client

A lightweight client application (such as our Android app) that handles screen display and user gestures, while delegating all business logic, inventory validation, and pricing calculations to the central backend (ADR-017).

• Why it matters: Prevents "split-brain" bugs where prices on a mobile app differ from prices on the website.
• Where to see it: Demonstrated on the Mobile Companion.

Need → Pick → Pay

The three-step phone journey: say what you need, pick a real bouquet, then confirm delivery and payment. Used by the Android companion and the Path B mobile-web concierge. Not a new requirement ID — it is the screen map in the native mobile UX spec.

• Why it matters: It keeps the phone focused. Tiles and SSE stay on the web workspace.
• Where to see it: Mobile Companion and Path B.

Honesty Loop

Detect a web-vs-phone mismatch, open one issue, ship the smallest fix, then prove it on a real device — or leave the status Unknown.

• Why it matters: A merged ticket is a claim. A probe is proof.
• Where to see it: Mobile Companion and Claim vs probe.

Keep Learning and Apply

Continuous learning from build history, applied into durable harness artifacts. Knowledge First reads the vault; Keep Learning and Apply grows it. A retrospective or honesty pass that does not change a skill, sensor, or guide is incomplete.

• Why it matters: Without apply, every runner rediscovers the same failure class.
• Where to see it: Guides + Sensors layers; skill-matrix work (#433); coherence findings → sensors; journal Claim vs probe.

BFF (Backend-for-Frontend)

A secure gateway server that translates client requests from web browsers or mobile apps into internal domain commands.

• Why it matters: It prevents public browsers from ever connecting directly to databases or internal message queues.
• Where to see it: Illustrated on the System Stack.

Least-Data & Ephemeral Shredding

A privacy-first design principle (ADR-020) where sensitive customer information (such as physical delivery addresses) is isolated in an encrypted table and automatically purged after a 14-day fulfillment window.

• Why it matters: Eliminates the risk of massive customer data breaches by refusing to build permanent PII honeypots.
• Where to see it: Detailed on Privacy CRM.

Edge Wallet

An encrypted notebook on the customer’s phone. After a confirmed order, the companion stores a receipt locally (Android Keystore). Names and card wording stay on the device. The store only ever sees an opaque product/order token if a reorder is sent later.

• Why it matters: Repeat shopping does not require a central address book of customers.
• Honesty: The save is live and has been probed. The Need-screen reorder button is on main (!459 / #404). Write and tap remain two facts. Play empty-wallet vs receipt-present facts stay on the companion ledger.
• Where to see it: Mobile Companion and Privacy CRM.

Florist Staff Console

The /florist page on the live shop. Florists see orders and Contact Florist requests in a browser. It is not a second native app.

• Why it matters: Fulfillment stays on the same store hostname as the customer shop, with least-data reads.
• Where to see it: Path B Case Study.

Project & Governance Terms

Path B

The code name for our reference flower shop implementation at https://aea.artof.link. It demonstrates the Adaptive Workspace and customer journeys in action. The pilot host is an evening demo window by default (see Pilot demo window), not a 24/7 always-live claim.

• Where to see it: Path B Case Study.

Pilot demo window

Sponsor schedule for the Path B AWS pilot (aea.artof.link): default online daily 20:00–22:00 Europe/Berlin; otherwise down unless woken via Lambda with a short lease. Not 08:00–20:00 office hours. Phase 1 keeps MSK and NAT running. Off-window public origin serves a resting HTML page via ALB fixed-response (infra/aws/static/offline.html) — Probed 2026-09-17. Schedule/wake Lambda automation remains Documented until probed in git. Distinct from NFR-003 assistant availability (local/fail-closed path) and from architecture.artof.link (GitLab Pages).

• Where to see it: Path B honesty; Stack ledger; Comparison ledger.

Probe

A verification action performed on real hardware or live servers to prove that a feature works as claimed, rather than assuming it works because a ticket was closed.

• Why it matters: "Verified" is a claim until backed by a probe. If an unverified feature has not been tested, its status remains Unknown.
• Where to see it: Illustrated in the Journal as Claim vs probe (the same incident the comparison page calls Daily-brief honesty).

CF-NNN (Coherence Finding Codes)

An internal tracking identifier for an architectural discrepancy or falsifiable claim. Each finding follows a strict 1-finding → 1-issue → 1-branch discipline until verified or resolved.

• Where to see it: Referenced in the Comparison.

ID Freeze

A governance rule: once a requirement (FR/NFR) or business goal ID is assigned in canonical project records, it is never renumbered or reused, preserving traceability across years of commits.

Fourteen Hats (Roles)

The 14 specialized quality perspectives AEA uses to inspect code and architecture (e.g. UX Designer, AppSec Auditor, Cost Guardian, Performance Guardian). They represent areas of review, not a 14-person bureaucracy.

• Where to see it: Listed on the Schema.

Taxonomy Map Only

A related-work idea we recorded so later sessions do not forget it. It is not a live shop feature and not a new requirement ID.

• Why it matters: Public posts about agent memory or cost playbooks can look like product changes. The honest-status ledger says when they are only a map.
• Where to see it: Comparison ledger (10 Sep X-scan row) and Related posts are not the shop.

Lesson Candidate

A short inbox note after a run: what failed, what changed, which fix worked. It is not an automatic rewrite of skills or canonical docs.

• Why it matters: Reusing a correction beats growing one giant prompt. Promoting it still needs a Knowledge Guardian pass.
• Where to see it: Comparison. Follow-up ticket #412; not shipped as a live shop feature.

Agent coordination vocabulary

Autonomy Ladder

Evidence-backed promotion of agent (or routine) autonomy across five levels: 0 Observe, 1 Prepare, 2 Execute-with-approval, 3 Schedule-or-trigger, 4 Coordinate-specialists. Promote only when prior-level runs leave durable proof; demote when quality degrades. Autonomy is a runtime privilege, not a permanent label.

• Why it matters: Jumping from first demo to unattended work turns agents into always-on confusion. Trust expands in the same order as evidence.
• Where to see it: Schema — Agent coordination; maps onto Permissions + Loop + Observability. External learning cited from 0xwhrrari X Article (Keep Learning, not product endorsement).

Approval by Reversibility

Finish reversible work; park irreversible gates for a human. Irreversible examples: send, publish, purchase, delete, production change, legal commitment. A good run completes the reversible majority, stages the exact next action, and stops at the boundary — it does not stall at 10% because approval is needed later.

• Why it matters: Task size is a weak approval signal. Undoability is a better one. Keeps autonomy useful without becoming reckless.
• Where to see it: Schema — Agent coordination; same spirit as fail-closed Domain Services and MRC merge gates. External learning: 0xwhrrari.

Handoff Packet

A compact ownership transfer between agents or roles — not a full transcript. Minimum fields: from, to, objective, artifacts, decisions, constraints, open_questions, next_gate. Artifacts hold detail; the packet holds state; the thread holds discussion.

• Why it matters: Copying whole chats pollutes context and hides who owns the next proof. Compact packets make multi-agent graphs auditable.
• Where to see it: Schema — Agent coordination; complements Shared Understanding and vault memory outside chat. External learning: 0xwhrrari.

Account Connection vs Role Authority

Connecting an account or tool is plumbing (what the shared environment can reach). A role contract is permission (what this agent may do with that reach). Keep the two decisions separate. One careless connection is larger than one agent when sessions are shared.

• Why it matters: "Connected" is not "authorized." Plumbing ≠ permission — same honesty as Domain Services deciding stock while AI only interprets.
• Where to see it: Permissions layer; Schema — Agent coordination. External learning: 0xwhrrari.

Independent Checker

The builder is not the verifier. Generation and approval use separate prompts, rubrics, or roles — same spirit as MRC vs implementer and probe-before-status-words. Add a checker before promoting autonomy on the ladder.

• Why it matters: Self-review feels optimistic; independent evidence moves the loop.
• Where to see it: Team roles (MRC merges); Sensors + Observability; Schema — Agent coordination. External learning: 0xwhrrari.

Decision layer vocabulary

Decision Layer

A named control surface separate from generative LLM text: cheap typed judgments that route, triage, score, or stop work. Generative models write and reason; the decision layer returns constrained answers; code executes and owns irreversible gates. Maps onto AEA Loop + Graph routing and Permissions approval — not a second product brain and not a Path B vendor SDK.

• Why it matters: Mixing “write me an answer” with “which worker next?” hides cost, confidence, and ownership. Naming the decision layer keeps routing inspectable.
• Where to see it: Schema — Decision layer; complements Agent coordination. External learning: Codila (Keep Learning, not TypeSafe/Jev endorsement).

Typed Decision (Choice · Score · Gate)

Three plain shapes for a judgment: Choice (pick one predefined option + probabilities), Score (position on a described scale), Gate (yes/no probability / stop-continue). External literature may say Noul for Gate. AEA adopts the shapes as vocabulary — not a requirement to call any vendor API.

• Why it matters: Constrained answer spaces are cheaper to price, test, and fail-closed than free-form model prose for routing.
• Where to see it: Schema — Decision layer. External learning: Codila.

Rebuild Option Menu

When offering a Choice, rebuild the option list from current worker, tool, or domain state. Do not reuse a stale menu from an earlier turn.

• Why it matters: Stale options are a honesty failure class — the harness routes to workers that no longer exist or misses ones that do.
• Where to see it: Sensors + Shared Understanding; Schema — Decision layer. External learning: Codila.

Cost Per Decision

Track cost per completed decision or task, not only token rates ($/MTok). Useful for comparing typed-decision paths with generative calls. Vendor demo unit costs (e.g. Browser Use $0.0039) are not AEA Path B evidence until probed on our stack.

• Why it matters: Token price alone can hide retries, human review, and wrong-route waste. Cost Guardian already cares; this names the unit.
• Where to see it: Observability + Cost Guardian hat; Schema — Decision layer. External learning: Codila.

Model-tier Choice

A typed Choice that picks a model tier (e.g. fast / capable / expensive) from a rebuilt option menu before spend. Home: Cost Guardian + Observability + decision layer. External literature may show this as ModelRouterMiddleware (LangChain harness-with-Jev). AEA adopts the pattern name — not a requirement to install LangChain Typesafe middleware or TypeSafe/Jev.

• Why it matters: Routing every turn to the largest generative model hides cost; a cheap Choice before the generative call is inspectable and priceable ($/decision).
• Where to see it: Schema — Decision layer; Cost Guardian. External learning: LangChain — Building a Harness with Jev; Holmberg audit recipes.

AutoMode pre-tool Gate

A typed Gate (yes/no probability / stop-continue) run before a side-effecting tool executes. Maps onto AEA irreversible park list (#441): send / publish / purchase / delete / production / legal. External literature may say AutoModeMiddleware. AEA adopts the pattern name — not a vendor SDK.

• Why it matters: Generative “I will call bash/send” is not the same as Permissions allowing the act. Park first; Probe/Honesty/Unknown stay intact.
• Where to see it: Permissions + Schema — Decision layer; agent-OS Approval by reversibility. External: LangChain — Building a Harness with Jev.

Agentic workflows vocabulary (Anthropic Keep Learning)

Thin terms from Anthropic Building effective agents (Dec 2024) via Keep Learning — not an Anthropic product endorsement and not Path B shop UI. Status until Pages probe: Documented.

Workflow (predefined path)

A system where LLMs and tools follow a predefined code or guide path. In AEA: playbooks, CF sequences, and fixed sensor gates — predictable orchestration.

• Why it matters: Naming Workflow vs Agent stops treating every Loop turn as unbounded autonomy.
• Where to see it: Schema — Agentic workflows; Guides + Loop. External: Anthropic (Keep Learning).

Agent (model-directed process)

A system where the LLM dynamically directs process and tool use within bounds. In AEA: the Interpret→Act→Verify→Remember Loop inside Permissions, autonomy ladder, and irreversible park list — not an open-ended shop agent.

• Why it matters: Flexibility without park list is a honesty risk on Path B.
• Where to see it: Schema — Agentic workflows; Loop + Permissions. External: Anthropic.

Augmented LLM

Building block: model + retrieval + tools + memory. AEA map: retrieval → Memory/vault/Knowledge First; tools → Domain Services + ACI; memory → DATE_RE / committed vault (not chat-only).

• Why it matters: Makes the triad explicit so “just add an agent framework” is not mistaken for Outer Harness work.
• Where to see it: Schema — Agentic workflows. External: Anthropic.

Environment Ground Truth

Before the next Loop step, take probeable feedback from the environment (tool result, sensor, clip, CI log) — not model self-confidence.

• Why it matters: Same family as Probe / Honesty / Unknown and fail-closed Sensors.
• Where to see it: Sensors + Observability; Schema — Agentic workflows. External: Anthropic.

Measured Complexity

Prefer simple composable patterns; add complexity only when a measured benefit justifies latency/cost. Maps to When Not to Grow the Harness + cost per decision.

• Why it matters: Heavy frameworks obscure prompts and tempt unearned layers.
• Where to see it: Decision Framework / When Not to Grow (vault paper); Cost Guardian; Schema — Agentic workflows. External: Anthropic.

ACI (Agent-Computer Interface)

Craft tool names, docs, and argument shapes with the same care as HCI — so models (and humans) misuse tools less. Maps to Guides + Permissions boundaries.

• Why it matters: Bad tool interfaces cause compounding errors that look like “model failure.”
• Where to see it: Guides layer; Schema — Agentic workflows. External: Anthropic.

Related Documentation

• Framework Home — Core formula and overview.
• Architecture Blueprint — The 6 layers and execution loop.
• Comparison & Visual Guide — 5-floor building model.
• System Stack — Cloud infrastructure and request flow.
• Project Journal — The story behind the architecture.

Wiki vs project layers (IPOF)

Wiki (know) holds durable concepts; projects (do) hold hot delivery briefs via Inputs/Process/Outputs/Feedback. Keep Learning from Second Brain OS (two-layers.md) — Documented complement to AEA's four-vault taxonomy (#489). Not an Obsidian product dependency.

• Where to see it: Comparison ledger; harness paper XVIII-H; issue #489.

Dual-claim / contradiction page contract

When two vault facts conflict, surface both (dated dual claim) instead of silent overwrite. Strengthens Honesty beyond Unknown. Distinct from Annatar forgetting/TTL (#481/#485). Documented (#490).

• Where to see it: Honesty / Observability; harness paper XVIII-H; issue #490.

Vault health sensors

Computational checks for orphan notes, broken links, and vault metrics — Knowledge Guardian Sensors pattern from SBOS scripts//orphans. Documented (#493). Not Live shop health.

• Where to see it: Sensors; harness paper XVIII-H; issue #493.

Canonical rules file with tool pointers

One shared rules file that every coding agent reads, with thin pointer files per tool that only say where to look. Keep Learning from steipete/agent-scripts — Documented complement to AEA's generated skill adapters (#502). Must never hold account IDs, private hosts or secrets. Not Live.

• Where to see it: Guides; harness paper XVIII-I; issue #502.

Skill front-matter validation

A check that each canonical skill has parseable front matter, a name that matches its folder, and a short routing description, plus a read-only audit that each tool can see the skills. Extends the existing 6-way drift guard (#503). Documented.

• Where to see it: Guides / Sensors; harness paper XVIII-I; issue #503.

Model and effort routing by role

A vendor-neutral policy that names a capability tier and effort level per role, with escalation triggers that reuse the sponsor gate, MRC and the repeated-error rule. Proposal only (#504), related to Model-tier Choice (#473). Cost effect is Unknown until measured.

• Where to see it: Decision layer / Cost Guardian; harness paper XVIII-I; issue #504.

Fresh-context verifier

A verifier that does not run inside the producer's conversation or reuse its plan; it reads the artifact and the rule directly and cites the rule for each finding. Extends the independent verifier (paper XV.C). Proposal, Documented (#509). Effect on defects Unknown.

• Where to see it: Guides / Independent verifier; harness paper XVIII-J; issue #509.

Source independence

A cross-check only counts if its anchor is not the claim's own source: a test that ran, a live probe or a frozen rule, not another agent's summary of the same document. Supports the Documented, Probed and Live labels. Proposal (#509). Not Live.

• Where to see it: Honesty labels; harness paper XVIII-J; issue #509.

Fake-edge audit

Asking of every "and then" whether the next step needs the previous result, so needless waits can be removed and independent work run together. Applied first as a review of CI stage barriers (#510). Saving Unknown until measured.

• Where to see it: Sensors / CI; harness paper XVIII-J; issue #510.

Gate-change declaration

A one-line Gate-change: <what changed; tighten or relax> in an MR that edits a merge gate itself: a guard script, a guard test, fixtures, an exception list or the CI file. It applies the evaluator-isolation idea: the change under review must not quietly edit the check that scores it. Such an MR is not self-merged. Proposal, Documented (#525). Effect Unknown.

• Where to see it: Permissions / Sensors; harness paper XVIII-K; issue #525.

Anchored lesson

A lesson note that cites something which ran and can be re-checked (a CI job, a commit, a probe output, a test result). Only anchored lessons are promoted from the inbox into the vault; the note's own summary does not count (see Source independence). Documented (#526). Not Live.

• Where to see it: Memory / Keep Learning; harness paper XVIII-K; issue #526.

Adoption record

A short block filled in before a new tool, service or dependency is adopted: the prior art searched, the last commit or release, the licence and its obligations (AGPL, commercial), the open-issue load, the security model (sandbox, data captured, credentials reachable) and the measured need. Keep Learning reviews incoming ideas; this checks the outside world before adoption. pip-audit covers known CVEs only. Template: research/templates/adoption-record.md (#527). Documented until one real adoption uses it.

• Where to see it: Guides / Keep Learning / Permissions; harness paper XVIII-L; issue #527.

Passive DAST baseline

A scheduled, non-intrusive scan of our own deployed hosts from the outside (for example an OWASP ZAP baseline scan), limited to an allowlist kept under the permissions layer, with results posted as guard verdicts. Report-only first, promoted to blocking only through a Gate-change: line. AI pentesting stays parked. Proposal, Documented (#528). No job exists yet.

• Where to see it: Permissions / Observability; harness paper XVIII-L; issue #528.

Confidence routing

A written policy that turns a typed decision's confidence into an action: act above a high threshold, ask a stronger model or a human in between, never act on the cheap answer below a low one. Thresholds are per decision kind (a Gate before an irreversible action uses the strictest), every question has an other/none exit, and a calibration check on labelled data must pass, ideally after a shadow run, before a band is trusted. The park list still applies whatever the confidence. Proposal, Documented (#545). The decision layer logs confidence today but nothing acts on it.

• Where to see it: Decision layer / Observability; harness paper XVIII-M; issue #545.

Task-property rule

A short table that names, per task type, how checkable success is (strong, weak or delayed oracle), the horizon, reversibility and autonomy, and the evidence each needs. Strong oracle: a CI guard. Weak oracle: clip probe plus honesty ledger. Irreversible: park list. Proposal, Documented (#544); the weak-oracle plus high-autonomy case is undefined today.

• Where to see it: Guides / Sensors; harness paper XVIII-M; issue #544.

Rule class (Hard or Default)

Every always-on rule says whether it can ever bend. Class: Hard rules are never overridden by context or a request and change only through an ADR or decision record; Class: Default rules adapt to context, and a deviation is stated in the MR. Each rule carries a one-line Why: linking the CF, ADR, issue or decision that created it. Documented (#548). Not Live.

• Where to see it: Guides; harness paper III.C and XVIII-N; issue #548.

Data freshness stamp

A line on any brief, Finding or report that cites external state: Data: <source> as of <time>, age <n>. Cached files carry last_sync:. Data past its time-to-live is reported as Unknown, not as a value, and each integration has a written degraded mode. Documented (#549). Not Live.

• Where to see it: Memory and State / Observability; harness paper VI.D and XVIII-N; issue #549.