# Architecture

**Herma:** context-shimming AI middleware for configurable coding harnesses -- intercepts requests via keyword, semantic, or micromodel rules to respond directly or shim atomic noun, verb, and URI context from a user-configured database before LLM execution.

```mermaid
flowchart LR
  H["Configurable Coding Harness<br/>muse-code / opencode / claude-code / codex"] --> E["Cloudflare Worker Edge<br/>D1 + HSTS/CSP + x-edge-auth"]
  E --> G["Harness Gate & Caller Scope<br/>hmk_ key:<id> + builtin lock"]
  G --> T["3-Tier Trigger Engine<br/>1. Keyword  2. Semantic  3. Micromodel"]
  S[("Caller-Isolated Provisions + Context DB<br/>SQLite / D1 / Governed Tessera / Handshake")] --> T
  T -->|"action: respond_directly"| D["Direct Protocol Response<br/>0 upstream tokens + SHA-256 Receipt"]
  T -->|"action: shim_context"| I["Context Shim + Entity Memory<br/>[NOUN/VERB CONTEXT] + URIs + Outcomes"]
  I --> U["Upstream LLM Endpoint<br/>/v1/chat/completions · /v1/responses · /v1/messages"]
```

## Components

- `herma/errors.py` -- RFC 9457 `problem+json` error hierarchy (`403 harness_required`, `403 admin_required`, `403 builtin_protected`, `403 contributor_tier_refused`, `409 version_conflict`).
- `herma/schemas.py` -- strict Pydantic v2 models for `Provision` (`shim_context` / `respond_directly` + `context_refs`), `ContextEntry` (`noun` / `verb` / `detail` + `version`), `WorkingEntity`, `RuleOutcomeRecord`, `InsightsResponse`, `DryRunResponse`, and `InjectionReceipt`.
- `herma/harness_gate.py` -- constant-time `hmk_` verification, `caller_scope = key:<key_id>`, credentialed personal-assistant access, `configure` harness attestation, and refusal of any model ID containing `contributor`.
- `herma/triggers/` -- `keyword.py`, `semantic.py`, `micromodel.py`, and `engine.py`.
- `herma/memory.py` -- zero-LLM deterministic entity extraction (`file_path`, `code_symbol`, `tessera_uri`, `statute_card_id`, `error_signature`) and reviewable `candidate_provisions` synthesis.
- `herma/store.py` -- caller-partitioned SQLite WAL store (`provisions`, `context_entries`, `harness_keys`, `injection_receipts`, `working_entities`, `rule_outcomes`), single-statement atomic SQL CAS, Layer-1 Governance Lens + SHA-256 blob verification, Tessera store sync, and remote handshake sync.
- `herma/injector.py` -- multi-protocol envelope extraction, `[NOUN/VERB CONTEXT]` rendering, direct-response assembly, turn deduplication, entity extraction, and SHA-256 receipts.
- `herma/proxy.py` -- direct-response short-circuiting (`chat.completion`, `response`, `message`), turn telemetry persistence, and upstream forwarding (JSON and streaming SSE).
- `herma/api/` -- FastAPI app (`:7730`) serving caller-isolated `/v1/*` endpoints, `/v1/memory`, `/v1/outcomes`, `/v1/insights`, read-only `POST /api/preview`, stateless JSON-RPC 2.0 `POST /mcp`, discovery routes (`/llms.txt`, `/llms-full.txt`, `/.well-known/agent-card.json`, `/robots.txt`, `/healthz`, `/favicon.svg`), and responsive SVG-branded HTML pages.
- `deploy/cloudflare/` -- 24/7 native Cloudflare Worker + D1 (`ta-amps-herma`) + `TESSERA` Service Binding with full caller-isolation, CAS, governance lens, entity memory, preview, and MCP parity.

## Invariants

| Id | Always true | Checked by |
|---|---|---|
| H01 | Personal assistants with scoped keys are accepted; browser navigation and cookie authentication are refused | `test_personal_assistant_credentials_and_browser_navigation`, `test_http_edge_lockdown_and_dry_run_across_wire_formats` |
| H02 | Provision management and remote sync require both configure scope and explicit matching X-Herma-Harness attestation | `test_personal_assistant_credentials_and_browser_navigation`, `test_route_only_key_cannot_configure` |
| H03 | Contributor-tier models (any model ID containing contributor, including -contributor) are refused across outbound LLM payloads, micromodel trigger classifiers, provider plans and operator grants before offline fallback | `test_tier3_micromodel_classifier_and_contributor_refusal`, `test_http_edge_lockdown_and_dry_run_across_wire_formats`, `test_governance_lens_blob_sha256_integrity_and_contributor_offline_refusal`, `test_contributor_models_are_refused_in_plans_grants_and_configuration` |
| H04 | Tier-1 keyword, bounded regex, path-glob, and tool-name triggers match deterministically without network calls | `test_tier1_keyword_regex_path_and_tool_triggers` |
| H05 | Tier-2 semantic triggers match paraphrased intent without literal keyword overlap | `test_tier2_semantic_paraphrase_without_literal_id` |
| H06 | Tier-1 or Tier-2 hits short-circuit Tier-3 micromodel calls when trigger mode is any | `test_engine_short_circuits_micromodel_when_keyword_matches` |
| H07 | Single-statement atomic SQL compare-and-set versions prevent silent provision and context_entries overwrites, Tessera blob URIs verify SHA-256 digests, and remote handshakes clamp max_chars | `test_cas_conflict_and_tessera_blob_sync`, `test_remote_handshake_clamps_max_chars`, `test_multi_caller_non_poisoning_builtin_lock_admin_keys_and_cas_parity` |
| H08 | Multi-turn conversations deduplicate once_per_conversation provisions and HERMA_EDGE_SECRET blocks direct origin traffic lacking x-edge-auth | `test_http_edge_lockdown_and_dry_run_across_wire_formats` |
| H09 | Matched context_refs shim bounded atomic noun, verb, and detail entries from caller-scoped context_entries or governed Tessera stores and record shimmed_context_refs in the receipt | `test_store_context_entries_and_tessera_noun_verb_resolution`, `test_api_context_database_and_noun_verb_shimming` |
| H10 | Provisions with action=respond_directly return protocol-faithful completions across chat_completions, responses, and messages without invoking upstream LLM transport while recording a SHA-256 receipt | `test_direct_response_short_circuits_upstream_across_all_protocols`, `test_cloudflare_worker_context_shim_and_direct_response_parity` |
| H11 | Caller-scoped provisions, context_entries, and receipts never poison or leak across keys, system_builtin records return 403 builtin_protected on non-admin writes, and /v1/admin/keys requires bootstrap/admin credentials | `test_multi_caller_non_poisoning_builtin_lock_admin_keys_and_cas_parity` |
| H12 | Layer-1 Tessera governance refuses status:quarantined records, requires status:verified across surfaces, enforces visibility_scope/cohort/harness tags, and verifies 64-hex SHA-256 digests on tessera://blobs URIs | `test_governance_lens_blob_sha256_integrity_and_contributor_offline_refusal` |
| H13 | Deterministic regex extraction tracks 5 entity kinds per (caller_scope, project_tag), attributes Turn N error signatures to Turn N-1 fired rules as retry_error, and emits Provision-valid candidate_provisions without mutating active rules | `test_deterministic_entity_memory_retry_outcomes_and_candidate_insights_parity` |
| H14 | Public POST /api/preview evaluates system_builtin rules with persisted=false, SVG brand chrome renders cleanly, and discovery routes plus stateless JSON-RPC POST /mcp match across Python and Cloudflare Worker | `test_public_preview_svg_brand_chrome_discovery_and_stateless_mcp_parity` |
| H16 | Micromodel decisions require boolean apply and finite numeric confidence in [0,1], malformed replies do not activate fallback, and offline trigger evaluation skips classifier and remote embedding requests | `test_micromodel_requires_typed_decision`, `test_malformed_model_reply_does_not_activate_fallback`, `test_offline_engine_blocks_all_provider_calls`, `test_preview_and_dry_run_never_call_configured_trigger_providers`, `test/triggers.test.js` |
| H17 | Operator-funded conversation turns require the caller's own exact provider/model grant; uncertain-outcome failover requires that caller's grant plus the plan opt-in; one upstream model identity is reachable through one route per plan and is held against other routes during its rate or quota limit | `test_direct_turns_need_the_callers_own_exact_grant`, `test_uncertainty_grant_defaults_off_and_a_plan_cannot_supply_it`, `test_plans_refuse_a_second_credential_for_the_same_upstream_model`, `test_rate_limit_holds_the_upstream_model_against_other_credentials`, `test/provider_grants.test.js` |
| H18 | Served pages, discovery text, starter seed data and runtime sources never name a retired pack, and fabric imports trust only the current producer surfaces: Tessera, Herma, Eranos and Agora | `test_served_text_names_no_retired_pack`, `test_seed_data_and_runtime_sources_name_no_retired_pack`, `test_governance_lens_trusts_the_same_producer_surfaces` |
| H19 | Starters synced from Tessera into system_builtin fire for routed callers only when they carry fabric_governance that passes the Layer-1 lens, and Python and the Worker decide every stored row the same way | `test_synced_starters_fire_for_routed_callers_only_with_their_governance`, `test_stored_provisions_pass_the_lens_the_same_way` |