{
  "id": "2026-04-23-semantic-intent-layer-0221f2221c",
  "scope": "redkey",
  "source_of_truth": "repo",
  "source_path": "docs/specs/2026-04-23-semantic-intent-layer.md",
  "source_kind": "markdown",
  "visibility": "internal",
  "renderer_id": "design_doc.dreamborn-forge.generated.v1",
  "design_system": "dreamborn-design-system:forge",
  "generated_at": "2026-05-09T13:00:55.666Z",
  "artifact_type": "design_doc",
  "schema_version": "design_doc.generated.v1",
  "title": "Semantic Intent Layer",
  "summary": "Semantic Intent Layer Date: 2026 04 23 Status: Design Related: docs/specs/2026 04 23 brain architecture.md, docs/execution model.md Overview The intent layer sits between natural language expression and RedKey execution. A human (or agent) expresses what they want. The intent layer resolves that to RedKey workflow primitives, executes, and self heals when AP...",
  "format_source": "markdown",
  "sections": [
    {
      "title": "Semantic Intent Layer",
      "level": 1,
      "body": "**Date:** 2026-04-23  \n**Status:** Design  \n**Related:** `docs/specs/2026-04-23-brain-architecture.md`, `docs/execution-model.md`\n\n---"
    },
    {
      "title": "Overview",
      "level": 2,
      "body": "The intent layer sits between natural language expression and RedKey execution. A human (or agent) expresses what they want. The intent layer resolves that to RedKey workflow primitives, executes, and self-heals when APIs break — without human intervention.\n\nThis is what makes BezelIQ's \"never breaks\" guarantee possible.\n\n```\nHuman/AI expression\n        ↓\n  Intent Layer  ←──── BezelBrain (human judgment)\n        ↓        ←──── Agent Brain (system knowledge)\n        ↓        ←──── API Library (available capabilities)\n  RedKey Orchestration\n  (Claire → Engine → Workers)\n```\n\n---"
    },
    {
      "title": "Position in Stack",
      "level": 2,
      "body": "Today, Claire receives raw natural language and classifies it from scratch. The intent layer becomes Claire's upstream — it does the resolution work, Claire confirms and executes. As the intent layer matures, Claire's classification role narrows.\n\n```\nToday:    Human → roles.coordinator → Claire (classifies) → workflow\nFuture:   Human → Intent Layer (resolves) → roles.coordinator → Claire (confirms) → workflow\n```\n\nBoth paths coexist. The intent layer is additive, not a replacement.\n\n---"
    },
    {
      "title": "The New Agent: Intent Resolver",
      "level": 2,
      "body": "**Agent ID:** `resolver`  \n**Role topic:** `roles.intent` (new topic to be created on HCS)  \n**Model:** Sonnet — judgment is required  \n**Timer:** 30s (same as Engine)\n\nThe resolver subscribes to `roles.intent`. When a message arrives it:\n1. Pulls context from BezelBrain + Agent Brain + API Library\n2. Resolves the intent to a structured workflow spec\n3. Posts to `roles.coordinator` for Claire to execute\n\nThe resolver never executes work directly. It resolves and hands off. Execution stays in the existing layer.\n\n---"
    },
    {
      "title": "Resolution Process",
      "level": 2,
      "body": "```\n1. Receive intent message from roles.intent\n   { content: \"find all HubSpot deals closing this quarter with no contact in 30 days\" }\n\n2. Query in parallel:\n   - BezelBrain: semantic search for relevant corporate knowledge + past decisions\n   - Agent Brain: semantic search for relevant resolution patterns + API behavior\n   - API Library: semantic search for capable APIs (\"CRM\", \"deal pipeline\", \"contact history\")\n\n3. Assess:\n   - Which APIs can fulfill this? (HubSpot — authenticated, available)\n   - Has this intent been resolved before? (check Agent Brain)\n   - Any corporate preferences that apply? (check BezelBrain)\n\n4. Resolve → structured workflow spec:\n   {\n     workflow_type: \"data_query\",\n     steps: [\n       { role: \"developer\", instruction: \"Query HubSpot for deals...\", api: \"hubspot\" }\n     ],\n     confidence: 0.92,\n     reasoning: \"HubSpot is the connected CRM. Matched prior resolution pattern.\"\n   }\n\n5. Post spec to roles.coordinator → Claire picks up\n```\n\n---"
    },
    {
      "title": "Confidence Model",
      "level": 2,
      "body": "| Confidence | Action |\n|---|---|\n| ≥ 0.85 | Execute directly — post to coordinator |\n| 0.60 – 0.84 | Present plan to human for confirmation before posting |\n| 0.40 – 0.59 | Ask one clarifying question, then re-resolve |\n| < 0.40 | Escalate to exec role with explanation |\n\nConfidence is calculated from: semantic match quality + prior resolution history + API availability + BezelBrain alignment.\n\n---"
    },
    {
      "title": "Self-Healing Loop",
      "level": 2,
      "body": "When a worker posts `task.blocked` with a schema/API error, the engine escalates to the resolver instead of halting the workflow.\n\n```\nWorker posts task.blocked\n  { reason: \"api_schema_error\", detail: \"field 'close_date' not found\", api: \"hubspot\" }\n\n  ↓ Engine detects escalation condition\n\nResolver receives re-resolution request:\n  1. Classify failure type: schema_change | auth_expired | deprecated | rate_limit | unknown\n  2. Query Agent Brain: \"HubSpot close_date schema error\" → finds prior pattern if exists\n  3. Re-resolve: inspect HubSpot OpenAPI spec, find correct field name\n  4. Patch the step instruction with updated field mapping\n  5. Re-post the step to roles.developer\n\n  ↓ On success:\n  Write to Agent Brain via teach_agent:\n    \"HubSpot: close_date renamed to expected_close as of [date]\"\n\n  ↓ On failure (unresolvable):\n  Post to roles.exec with full context\n  Mark workflow step as blocked with human-readable explanation\n  Do not halt entire workflow — other independent steps continue\n```\n\nEvery self-heal writes a learning. The corpus grows with every failure.\n\n---"
    },
    {
      "title": "API Library Integration",
      "level": 2,
      "body": "The resolver has read access to `api_library` (pgvector on RedKey Supabase).\n\nWhen resolving intent, semantic search finds capable APIs:\n- \"I need weather data\" → Open-Meteo (free, no auth), OpenWeatherMap (key)\n- \"I need deal pipeline data\" → HubSpot (OAuth, connected), Salesforce (not connected)\n- \"I need company filings\" → SEC EDGAR (free, no auth)\n\nThe resolver:\n- Prefers already-authenticated connections\n- Falls back to free/public APIs when capability is equivalent\n- Flags when no capable API is available — surfaced in resolution output\n\n---"
    },
    {
      "title": "API Library Schema",
      "level": 2,
      "body": "```sql\nCREATE TABLE api_library (\n  id              uuid PRIMARY KEY DEFAULT gen_random_uuid(),\n  api_id          text UNIQUE NOT NULL,        -- 'hubspot', 'open-meteo', 'sec-edgar'\n  name            text NOT NULL,\n  description     text,\n  capabilities    text[],                      -- human-readable: [\"deal pipeline\", \"contact history\"]\n  capabilities_embedding vector(1536),         -- semantic search target\n  auth_type       text NOT NULL,               -- 'none' | 'api_key' | 'oauth'\n  spec_url        text,                        -- OpenAPI/Swagger spec URL\n  base_url        text,\n  status          text NOT NULL DEFAULT 'active', -- 'active' | 'degraded' | 'deprecated'\n  discovered_by   text,                        -- 'api-scout' | 'manual'\n  hcs_sequence    bigint,                      -- sequence number from library.apis topic\n  last_verified   timestamptz,\n  metadata        jsonb,\n  created_at      timestamptz DEFAULT now()\n);\n\nCREATE INDEX api_library_capabilities_idx ON api_library\n  USING hnsw (capabilities_embedding vector_cosine_ops);\n```\n\n---"
    },
    {
      "title": "API Scout Agent",
      "level": 2,
      "body": "Continuously discovers new APIs and publishes them to HCS `library.apis` topic.\n\n**Agent ID:** `api-scout`  \n**Role topic:** `roles.scout` (timer-driven, no inbound work items)  \n**Timer:** 6 hours  \n\n**Sources scanned:**\n- Public API directories (APIs.guru, RapidAPI public listings)\n- Government data portals (data.gov, EDGAR, census.gov)\n- GitHub repos tagged `public-api`\n- Hacker News \"Show HN\" posts with API launches\n- Product Hunt (filter: developer tools, APIs)\n\n**On discovery:**\n1. Fetch OpenAPI spec if available\n2. Generate semantic description of capabilities using Haiku\n3. Publish to HCS `library.apis` topic\n4. Listener writes to `api_library` table\n\n**HCS message schema:**\n```json\n{\n  \"type\": \"api.discovered\",\n  \"api_id\": \"open-meteo\",\n  \"name\": \"Open-Meteo\",\n  \"capabilities\": [\"current weather\", \"forecast\", \"historical weather\", \"air quality\"],\n  \"auth_type\": \"none\",\n  \"spec_url\": \"https://open-meteo.com/en/docs\",\n  \"base_url\": \"https://api.open-meteo.com\",\n  \"discovered_by\": \"api-scout\",\n  \"client_id\": \"redkey\"\n}\n```\n\n---"
    },
    {
      "title": "Sentinel Agent",
      "level": 2,
      "body": "Monitors for competitive signals — specifically the self-healing + HCS combination being published before BezelIQ launches.\n\n**Agent ID:** `sentinel`  \n**Timer:** 1 hour  \n\n**Monitors:**\n- Hacker News: \"self-healing workflow\", \"self-healing API\", \"HCS agent\", \"Hedera orchestration\"\n- GitHub: new repos combining `hedera` + `orchestration` + `agent`\n- arXiv: papers on self-healing systems, agentic workflow execution\n- USPTO: patent filings on self-healing API/workflow systems\n- TechCrunch, VentureBeat: agent platform launches\n- Product Hunt: new launches tagged automation/workflow/agents\n- Hedera ecosystem: blog posts, developer announcements\n\n**On signal:**\n1. Write to `brain_memory` with `scope = 'corporate'`, `category = 'external'`, `source = 'sentinel'`\n2. Post alert to Atlas context injection (surfaces at next session start)\n3. If high relevance (competitive threat): also write to `roles.exec` for immediate review\n\n---"
    },
    {
      "title": "Expression Paths",
      "level": 2,
      "body": "Three ways intent enters the system:\n\n**1. Direct (current model)**\nHuman posts to `roles.coordinator`. Claire classifies from scratch. No resolver involved. Continues to work as-is.\n\n**2. Via BezelBrain**\nHuman promotes an idea via `brain-mcp` `contribute_to_project()`. brain-mcp posts to `roles.intent`. Resolver picks up with full BezelBrain context already available.\n\n**3. Via Atlas**\nAtlas has an `intent_resolve` tool in `mcp-atlas.json`. Justin describes what he wants in conversation. Atlas calls the tool. Resolver handles it.\n\n---"
    },
    {
      "title": "Learning Loop",
      "level": 2,
      "body": "```\nIntent expressed\n  ↓\nResolved → executed → complete\n  → write: \"intent X resolved via workflow Y, confidence Z\" → Agent Brain\n\nResolved → executed → step failed → self-healed → continued\n  → write: \"API X failure pattern, resolved by Y\" → Agent Brain\n\nResolved → executed → step failed → unresolvable → escalated\n  → write: \"intent X unresolvable with current API surface, reason Y\" → Agent Brain\n\nEvery execution teaches. Corpus grows. Self-healing improves.\n```\n\n---"
    },
    {
      "title": "What Gets Built (Implementation Sequence)",
      "level": 2,
      "body": "1. **Migration 014** — `brain_memory` table (brain architecture prerequisite)\n2. **Migration 015** — `api_library` table\n3. **`library.apis` HCS topic** — created on testnet\n4. **`roles.intent` HCS topic** — created on testnet\n5. **`brain-mcp` Edge Function** — on RedKey Supabase\n6. **`atlas-context.js` update** — BezelBrain section injection\n7. **`api-scout` agent** — definition + runner wiring\n8. **`sentinel` agent** — definition + runner wiring\n9. **`resolver` agent** — definition + runner wiring, `contribute_to_project` bridge\n10. **Engine update** — self-healing escalation to resolver on `task.blocked`\n11. **`mcp-atlas.json` update** — add `intent_resolve` tool\n\n---"
    },
    {
      "title": "Open Problems",
      "level": 2,
      "body": "- **Knowledge decay** — BezelBrain needs a periodic review surface for aging ideas. Not blocking v1 but needed before BezelBrain gets large.\n- **Confidence tuning** — thresholds (0.85, 0.60, 0.40) are estimated. Need real execution data to calibrate.\n- **Spec-less APIs** — many public APIs have no OpenAPI spec. Scout needs a fallback: capability inference from docs pages via scraping + Haiku.\n- **OAuth token lifecycle** — token refresh, expiry handling for authenticated APIs. Needs a credential manager component."
    }
  ],
  "html_path": "artifacts/2026-04-23-semantic-intent-layer-0221f2221c.html",
  "json_path": "artifacts/2026-04-23-semantic-intent-layer-0221f2221c.json"
}