{
  "$schema": "https://github.com/ta-amps/ta-amps-hackathon/blob/main/hackathon/agents/schemas/architecture.schema.json",
  "schema_version": 1,
  "name": "herma",
  "summary": "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 caller-isolated database before LLM execution. Rules, deterministic entity memory, and atomic noun/verb entries load from SQLite/D1, governed Tessera stores and blobs, or remote handshake servers; personal assistants use the same scoped credentials as coding harnesses; contributor-tier models are refused.",
  "status": {
    "as_of": "2026-10-30",
    "stage": "prototype",
    "notes": "Natural-language Tasks (verbs) & Task Objects (nouns) direct lookup, PROV-HARNESS-FEEDS-GUIDE and PROV-LORA-MEMORY-ROUTING starters with full fabric_governance lens parity, Meta AI model-role matrix, reproducible training/ and eval/ artifacts, standalone Dockerfile, caller-isolated SQLite/D1 CAS, deterministic entity memory, and stateless JSON-RPC /mcp verified across Python and Cloudflare Worker + D1."
  },
  "docs": {
    "summary": "docs/summary.md",
    "architecture": "docs/architecture.md",
    "harnesses": "docs/harnesses.md",
    "setup": "docs/setup.md",
    "handoff": "docs/handoff.md"
  },
  "read_order": [
    "README.md",
    "docs/summary.md",
    "docs/architecture.md",
    "docs/harnesses.md",
    "docs/setup.md",
    "examples/provisions/README.md",
    "docs/handoff.md",
    "AGENTS.md"
  ],
  "commands": {
    "setup": "make setup",
    "check": "make check",
    "test": "make test",
    "demo": "make demo",
    "serve": "make serve",
    "architecture": "make architecture",
    "index": "make index"
  },
  "components": [
    {
      "id": "errors",
      "title": "RFC 9457 error hierarchy",
      "path": "herma/errors.py",
      "kind": "library",
      "domain": "neutral",
      "role": "Maps typed middleware, scope, builtin-protection, admin-lockdown, governance, harness, and contributor-tier refusals to deterministic HTTP statuses"
    },
    {
      "id": "schemas",
      "title": "Provision, context-entry, memory, insights, trigger, key, and receipt schemas",
      "path": "herma/schemas.py",
      "kind": "library",
      "domain": "neutral",
      "role": "Strict Pydantic models for caller-scoped provisions, versioned context entries, working entities, rule outcomes, candidate insights, 3-tier triggers, harness keys, and SHA-256 receipts",
      "tests": [
        "tests/test_triggers.py",
        "tests/test_herma.py"
      ]
    },
    {
      "id": "harness_gate",
      "title": "Configurable-harness access gate",
      "path": "herma/harness_gate.py",
      "kind": "library",
      "domain": "neutral",
      "role": "Verifies constant-time hmk_ secrets, enforces route/configure/admin scopes, allows credentialed personal assistants, and blocks every model ID containing contributor",
      "depends_on": [
        "errors",
        "schemas"
      ],
      "tests": [
        "tests/test_harness_gate_and_store.py",
        "tests/test_herma.py"
      ]
    },
    {
      "id": "memory",
      "title": "Deterministic anti-RAG entity extractor and candidate synthesizer",
      "path": "herma/memory.py",
      "kind": "library",
      "domain": "neutral",
      "role": "Extracts file_path, code_symbol, tessera_uri, statute_card_id, and error_signature entities via zero-LLM regexes and synthesizes reviewable candidate_provisions",
      "depends_on": [
        "schemas"
      ],
      "tests": [
        "tests/test_herma.py"
      ]
    },
    {
      "id": "triggers",
      "title": "Three-tier trigger engine",
      "path": [
        "herma/triggers/__init__.py",
        "herma/triggers/keyword.py",
        "herma/triggers/semantic.py",
        "herma/triggers/micromodel.py",
        "herma/triggers/engine.py"
      ],
      "kind": "library",
      "domain": "neutral",
      "role": "Evaluates Tier-1 keyword/regex/path/tool, Tier-2 semantic cosine, and Tier-3 micromodel classifier triggers with short-circuiting and pre-fallback contributor refusal",
      "depends_on": [
        "errors",
        "schemas",
        "harness_gate"
      ],
      "tests": [
        "tests/test_triggers.py",
        "tests/test_herma.py"
      ]
    },
    {
      "id": "store",
      "title": "Caller-isolated provision, context, entity memory, and outcome store + governed sync",
      "path": "herma/store.py",
      "kind": "library",
      "domain": "neutral",
      "role": "SQLite WAL store with composite caller_scope PKs, atomic SQL CAS, system_builtin protection, Layer-1 governed Tessera CAS/blob/noun-verb sync, entity memory, and rule outcomes",
      "depends_on": [
        "errors",
        "schemas",
        "harness_gate",
        "memory"
      ],
      "tests": [
        "tests/test_harness_gate_and_store.py",
        "tests/test_herma.py"
      ]
    },
    {
      "id": "injector",
      "title": "Multi-protocol context shimmer, entity tracker, direct-response builder & receipt minter",
      "path": "herma/injector.py",
      "kind": "library",
      "domain": "neutral",
      "role": "Extracts prompt/path/tool signals and deterministic entities across chat_completions, responses, and messages, attributes Turn N retry errors, shims caller-scoped context or builds direct responses, and mints SHA-256 receipts",
      "depends_on": [
        "harness_gate",
        "memory",
        "schemas",
        "store",
        "triggers"
      ],
      "tests": [
        "tests/test_api_and_proxy.py",
        "tests/test_herma.py"
      ]
    },
    {
      "id": "proxy",
      "title": "Direct-response short-circuit & upstream forwarding engine",
      "path": "herma/proxy.py",
      "kind": "library",
      "domain": "neutral",
      "role": "Evaluates caller-isolated active provisions, short-circuits respond_directly rules into protocol-faithful completions, or forwards shimmed payloads (JSON or SSE) to allowlisted upstream LLM endpoints",
      "depends_on": [
        "conversation",
        "errors",
        "harness_gate",
        "injector",
        "schemas",
        "store",
        "triggers"
      ],
      "tests": [
        "tests/test_api_and_proxy.py",
        "tests/test_herma.py"
      ]
    },
    {
      "id": "api",
      "title": "FastAPI HTTP service, context/memory/insights API, preview, discovery & stateless MCP",
      "path": [
        "herma/api/__init__.py",
        "herma/api/pages.py",
        "herma/api/app.py"
      ],
      "kind": "service",
      "domain": "neutral",
      "role": "Serves caller-isolated proxy, context, memory, outcomes, insights, read-only /api/preview, SVG brand pages, discovery routes, and stateless JSON-RPC /mcp behind HERMA_EDGE_SECRET lockdown",
      "depends_on": [
        "errors",
        "harness_gate",
        "memory",
        "proxy",
        "schemas",
        "store",
        "triggers",
        "conversation"
      ],
      "tests": [
        "tests/test_api_and_proxy.py",
        "tests/test_herma.py",
        "tests/test_retired_names.py"
      ]
    },
    {
      "id": "conversation",
      "title": "Typed work conversation",
      "path": [
        "herma/conversation.py",
        "herma/conversation_contracts.py",
        "herma/conversation_provider.py",
        "herma/provider_diagnostics.py",
        "herma/provider_health.py",
        "herma/conversation_state.py",
        "herma/conversation_schema.py",
        "herma/provider_plan.py",
        "herma/decision_provider.py"
      ],
      "kind": "library",
      "domain": "neutral",
      "role": "Caller-scoped typed proposals, per-caller operator grants, explicit provider-plan nouns with one upstream model identity per route, per-attempt spend reservations in exact microdollars and private attribution; native Muse/Ollama/OpenAI/Anthropic adapters and pure Jev worker wire preparation; no generated action execution",
      "depends_on": [
        "errors",
        "harness_gate",
        "schemas",
        "store"
      ],
      "tests": [
        "tests/test_conversation.py",
        "tests/test_provider_contracts.py",
        "tests/test_provider_plan.py",
        "tests/test_provider_diagnostics.py",
        "tests/test_provider_health.py",
        "tests/test_decision_provider.py",
        "tests/test_provider_accounting.py",
        "tests/test_provider_grants.py",
        "tests/test_conversation_storage.py",
        "tests/test_runtime_parity.py"
      ]
    },
    {
      "id": "cli",
      "title": "Command-line interface and end-to-end demo",
      "path": "herma/cli.py",
      "kind": "cli",
      "domain": "neutral",
      "role": "Provides seed, keys, context, dry-run, 3-tier Tessera-synced context-shim + direct-response demo, and serve commands",
      "depends_on": [
        "api",
        "errors",
        "harness_gate",
        "proxy",
        "schemas",
        "store"
      ]
    },
    {
      "id": "edge",
      "title": "Cloud Worker & Edge",
      "path": [
        "deploy/cloudflare/worker.js",
        "deploy/cloudflare/herma_engine.js",
        "deploy/cloudflare/d1-herma.sql",
        "deploy/cloudflare/wrangler.jsonc",
        "deploy/cloudflare/entry.js",
        "deploy/cloudflare/conversation.js",
        "deploy/cloudflare/provider_diagnostics.js",
        "deploy/cloudflare/provider_health.js",
        "deploy/cloudflare/conversation_state.js",
        "deploy/cloudflare/conversation_data.json"
      ],
      "kind": "edge",
      "domain": "neutral",
      "role": "24/7 native Cloudflare Worker + D1 (ta-amps-herma) + Tessera Cloud Service Binding with caller_scope isolation, atomic SQL CAS, deterministic entity memory, candidate insights, /api/preview, discovery routes, and stateless /mcp",
      "depends_on": [
        "api"
      ],
      "tests": [
        "tests/test_herma.py",
        "test/conversation.test.js",
        "test/provider_diagnostics.test.js",
        "test/provider_health.test.js",
        "test/provider_grants.test.js",
        "tests/test_retired_names.py",
        "tests/test_builtin_starters.py"
      ]
    }
  ],
  "invariants": [
    {
      "id": "H01",
      "statement": "Personal assistants with scoped keys are accepted; browser navigation and cookie authentication are refused",
      "enforced_by": "harness_gate",
      "checked_by": [
        "tests/test_harness_gate_and_store.py::test_personal_assistant_credentials_and_browser_navigation",
        "tests/test_api_and_proxy.py::test_http_edge_lockdown_and_dry_run_across_wire_formats"
      ]
    },
    {
      "id": "H02",
      "statement": "Provision management and remote sync require both configure scope and explicit matching X-Herma-Harness attestation",
      "enforced_by": "harness_gate",
      "checked_by": [
        "tests/test_harness_gate_and_store.py::test_personal_assistant_credentials_and_browser_navigation",
        "tests/test_harness_gate_and_store.py::test_route_only_key_cannot_configure"
      ]
    },
    {
      "id": "H03",
      "statement": "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",
      "enforced_by": "harness_gate",
      "checked_by": [
        "tests/test_triggers.py::test_tier3_micromodel_classifier_and_contributor_refusal",
        "tests/test_api_and_proxy.py::test_http_edge_lockdown_and_dry_run_across_wire_formats",
        "tests/test_herma.py::test_governance_lens_blob_sha256_integrity_and_contributor_offline_refusal",
        "tests/test_provider_grants.py::test_contributor_models_are_refused_in_plans_grants_and_configuration"
      ]
    },
    {
      "id": "H04",
      "statement": "Tier-1 keyword, bounded regex, path-glob, and tool-name triggers match deterministically without network calls",
      "enforced_by": "triggers",
      "checked_by": [
        "tests/test_triggers.py::test_tier1_keyword_regex_path_and_tool_triggers"
      ]
    },
    {
      "id": "H05",
      "statement": "Tier-2 semantic triggers match paraphrased intent without literal keyword overlap",
      "enforced_by": "triggers",
      "checked_by": [
        "tests/test_triggers.py::test_tier2_semantic_paraphrase_without_literal_id"
      ]
    },
    {
      "id": "H06",
      "statement": "Tier-1 or Tier-2 hits short-circuit Tier-3 micromodel calls when trigger mode is any",
      "enforced_by": "triggers",
      "checked_by": [
        "tests/test_triggers.py::test_engine_short_circuits_micromodel_when_keyword_matches"
      ]
    },
    {
      "id": "H07",
      "statement": "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",
      "enforced_by": "store",
      "checked_by": [
        "tests/test_harness_gate_and_store.py::test_cas_conflict_and_tessera_blob_sync",
        "tests/test_harness_gate_and_store.py::test_remote_handshake_clamps_max_chars",
        "tests/test_herma.py::test_multi_caller_non_poisoning_builtin_lock_admin_keys_and_cas_parity"
      ]
    },
    {
      "id": "H08",
      "statement": "Multi-turn conversations deduplicate once_per_conversation provisions and HERMA_EDGE_SECRET blocks direct origin traffic lacking x-edge-auth",
      "enforced_by": "api",
      "checked_by": [
        "tests/test_api_and_proxy.py::test_http_edge_lockdown_and_dry_run_across_wire_formats"
      ]
    },
    {
      "id": "H09",
      "statement": "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",
      "enforced_by": "injector",
      "checked_by": [
        "tests/test_herma.py::test_store_context_entries_and_tessera_noun_verb_resolution",
        "tests/test_herma.py::test_api_context_database_and_noun_verb_shimming"
      ]
    },
    {
      "id": "H10",
      "statement": "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",
      "enforced_by": "proxy",
      "checked_by": [
        "tests/test_herma.py::test_direct_response_short_circuits_upstream_across_all_protocols",
        "tests/test_herma.py::test_cloudflare_worker_context_shim_and_direct_response_parity"
      ]
    },
    {
      "id": "H11",
      "statement": "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",
      "enforced_by": "store",
      "checked_by": [
        "tests/test_herma.py::test_multi_caller_non_poisoning_builtin_lock_admin_keys_and_cas_parity"
      ]
    },
    {
      "id": "H12",
      "statement": "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",
      "enforced_by": "store",
      "checked_by": [
        "tests/test_herma.py::test_governance_lens_blob_sha256_integrity_and_contributor_offline_refusal"
      ]
    },
    {
      "id": "H13",
      "statement": "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",
      "enforced_by": "memory",
      "checked_by": [
        "tests/test_herma.py::test_deterministic_entity_memory_retry_outcomes_and_candidate_insights_parity"
      ]
    },
    {
      "id": "H14",
      "statement": "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",
      "enforced_by": "api",
      "checked_by": [
        "tests/test_herma.py::test_public_preview_svg_brand_chrome_discovery_and_stateless_mcp_parity"
      ]
    },
    {
      "id": "H16",
      "statement": "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",
      "enforced_by": "triggers",
      "checked_by": [
        "tests/test_triggers.py::test_micromodel_requires_typed_decision",
        "tests/test_triggers.py::test_malformed_model_reply_does_not_activate_fallback",
        "tests/test_triggers.py::test_offline_engine_blocks_all_provider_calls",
        "tests/test_api_and_proxy.py::test_preview_and_dry_run_never_call_configured_trigger_providers",
        "test/triggers.test.js"
      ]
    },
    {
      "id": "H17",
      "statement": "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",
      "enforced_by": "conversation",
      "checked_by": [
        "tests/test_provider_grants.py::test_direct_turns_need_the_callers_own_exact_grant",
        "tests/test_provider_grants.py::test_uncertainty_grant_defaults_off_and_a_plan_cannot_supply_it",
        "tests/test_provider_grants.py::test_plans_refuse_a_second_credential_for_the_same_upstream_model",
        "tests/test_provider_grants.py::test_rate_limit_holds_the_upstream_model_against_other_credentials",
        "test/provider_grants.test.js"
      ]
    },
    {
      "id": "H18",
      "statement": "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",
      "enforced_by": "edge",
      "checked_by": [
        "tests/test_retired_names.py::test_served_text_names_no_retired_pack",
        "tests/test_retired_names.py::test_seed_data_and_runtime_sources_name_no_retired_pack",
        "tests/test_runtime_parity.py::test_governance_lens_trusts_the_same_producer_surfaces"
      ]
    },
    {
      "id": "H19",
      "statement": "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",
      "enforced_by": "edge",
      "checked_by": [
        "tests/test_builtin_starters.py::test_synced_starters_fire_for_routed_callers_only_with_their_governance",
        "tests/test_runtime_parity.py::test_stored_provisions_pass_the_lens_the_same_way"
      ]
    }
  ],
  "import_rules": [
    {
      "id": "ring0-pure-contracts",
      "package": "herma",
      "package_root": "herma",
      "files": [
        "herma/errors.py",
        "herma/schemas.py",
        "herma/harness_gate.py"
      ],
      "must_not_import": [
        "herma.memory",
        "herma.store",
        "herma.triggers",
        "herma.injector",
        "herma.proxy",
        "herma.api",
        "herma.cli",
        "fastapi",
        "starlette",
        "httpx",
        "sqlite3",
        "tessera"
      ],
      "why": "Ring 0 holds pure schemas, error contracts, and stateless harness access gates with zero I/O"
    },
    {
      "id": "ring1-core-never-imports-doors",
      "package": "herma",
      "package_root": "herma",
      "files": [
        "herma/memory.py",
        "herma/triggers",
        "herma/store.py",
        "herma/injector.py",
        "herma/proxy.py"
      ],
      "must_not_import": [
        "herma.api",
        "herma.cli",
        "fastapi",
        "starlette"
      ],
      "why": "Core memory, trigger, store, and injection engines never depend on FastAPI or CLI entry points"
    },
    {
      "id": "package-never-imports-dev-roots",
      "package": "herma",
      "package_root": "herma",
      "files": [
        "herma"
      ],
      "must_not_import": [
        "tests",
        "scripts",
        "deploy"
      ],
      "why": "Runtime package code never imports test, build, or deployment folders"
    }
  ],
  "claims": [
    {
      "id": "HC1",
      "claim": "Herma evaluates keyword, semantic, and micromodel triggers to shim versioned provisions and URIs across chat_completions, responses, and messages while preserving caller-scoped access for coding harnesses and personal assistants",
      "status": "built",
      "evidence": [
        "tests/test_triggers.py::test_tier1_keyword_regex_path_and_tool_triggers",
        "tests/test_triggers.py::test_tier2_semantic_paraphrase_without_literal_id",
        "tests/test_api_and_proxy.py::test_http_edge_lockdown_and_dry_run_across_wire_formats"
      ]
    },
    {
      "id": "HC2",
      "claim": "Herma loads and syncs versioned provisions and atomic noun/verb context entries from governed Tessera CAS/blob/noun stores and remote handshake servers with SHA-256 digest checks",
      "status": "built",
      "evidence": [
        "tests/test_harness_gate_and_store.py::test_cas_conflict_and_tessera_blob_sync",
        "tests/test_harness_gate_and_store.py::test_remote_handshake_clamps_max_chars",
        "tests/test_herma.py::test_store_context_entries_and_tessera_noun_verb_resolution",
        "tests/test_herma.py::test_governance_lens_blob_sha256_integrity_and_contributor_offline_refusal"
      ]
    },
    {
      "id": "HC3",
      "claim": "Herma shims caller-isolated atomic noun, verb, and detail context or responds directly across all 3 LLM wire protocols with zero upstream token spend and zero cross-caller poisoning",
      "status": "built",
      "evidence": [
        "tests/test_herma.py::test_api_context_database_and_noun_verb_shimming",
        "tests/test_herma.py::test_direct_response_short_circuits_upstream_across_all_protocols",
        "tests/test_herma.py::test_cloudflare_worker_context_shim_and_direct_response_parity",
        "tests/test_herma.py::test_multi_caller_non_poisoning_builtin_lock_admin_keys_and_cas_parity"
      ]
    },
    {
      "id": "HC4",
      "claim": "Herma tracks deterministic working entities without embeddings, attributes retry errors across turns, and synthesizes reviewable Provision-valid candidate rules on /v1/insights without mutating active provisions",
      "status": "built",
      "evidence": [
        "tests/test_herma.py::test_deterministic_entity_memory_retry_outcomes_and_candidate_insights_parity"
      ]
    },
    {
      "id": "HC5",
      "claim": "Herma serves a zero-write interactive preview, SVG boundary-pillar chrome, discovery endpoints, and stateless JSON-RPC 2.0 /mcp in parity across FastAPI and Cloudflare Worker",
      "status": "built",
      "evidence": [
        "tests/test_herma.py::test_public_preview_svg_brand_chrome_discovery_and_stateless_mcp_parity"
      ]
    }
  ]
}