{"slug":"architecture/ENTITY_360_TWIN_TRIGGER_SCORING_GUARDRAILS","title":"Current Surface-Binding Doctrine","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/ENTITY_360_TWIN_TRIGGER_SCORING_GUARDRAILS.mdx","bytes":3783,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"## Current Surface-Binding Doctrine\n\n- Operational Workbench = the primary work surface; left sidebar nav; Twin sidebar pops out when needed.\n- Twin Workbench = full AI ecosystem surface (skills, knowledge, agents, prompts, conversational library).\n- Governance is embedded at every layer — not a separate workbench.\n- OpenWebUI is not the customer-facing product shell.\n- Twin / OpenWebUI runtime surfaces use the canonical Forest + Paper system language.\n- Midnight Executive is investor-deck / fundraising language only.\n\nUse older L1/L2 / workspace / knowledge-UI language in this file through that boundary if any historical phrasing remains.\n\n---\n\n# Entity 360 + Twin Trigger Scoring & Guardrails\n\n## Entity 360 API\n\n### Endpoints\n\n| Method | Path                   | Description                 |\n| ------ | ---------------------- | --------------------------- |\n| GET    | `/api/entity360/:id`   | Single entity 360           |\n| POST   | `/api/entity360`       | Single with layer selection |\n| POST   | `/api/entity360/batch` | Multiple entities           |\n\n### Request\n\n```json\n{\n  \"tenant_id\": \"uuid\",\n  \"spine_id\": \"uuid\",\n  \"layers\": [\"truth\", \"context\", \"signals\", \"memory\", \"goals\", \"relationships\"],\n  \"limits\": { \"context\": 10, \"signals\": 20, \"memory\": 15 }\n}\n```\n\n### Response Structure\n\n```typescript\ninterface Entity360 {\n  spine_id: string;\n  tenant_id: string;\n  entity_type: string;\n  display_name: string;\n  truth: { data, source_table, freshness, sources };\n  context: { recent: ContextItem[], total_count };\n  signals: { active: Signal[], summary: { critical, high, medium, low, info } };\n  memory: { recent: MemoryItem[], total_count };\n  goals: { active: Goal[], health: \"on_track\" | \"at_risk\" | \"off_track\" | \"no_goals\" };\n  relationships: { parent?, children[], related[] };\n  meta: { assembled_at, hydration_bucket, department, cache_hit, assembly_ms };\n}\n```\n\n## Twin Trigger Scoring\n\n### Severity Levels\n\n| Level    | Threshold               | Example                              |\n| -------- | ----------------------- | ------------------------------------ |\n| Critical | Immediate action needed | Health drop 15+, signal cluster 3+   |\n| High     | Action within 48h       | Renewal 30d + low health, 5+ tickets |\n| Medium   | Action within 1 week    | Engagement drop 30d, stale data      |\n| Low      | Monitor                 | ARR growth, context gap              |\n| Info     | Informational           | Data freshness, memory status        |\n\n### Confidence Scoring\n\nEach trigger produces a confidence score (0-1):\n\n- 0.95: Data-driven with clear threshold (renewal date, ARR change)\n- 0.90: Pattern-based with strong signal (health drop, signal cluster)\n- 0.85: Multi-source correlation (goal at risk, support escalation)\n- 0.80: Single-source inference (engagement drop)\n- 0.70: Heuristic (stale data)\n- 0.60: AI-derived (memory conflict)\n\n### Guardrails\n\n1. **Max 3 insights per entity per day** — prevents alert fatigue\n2. **Severity-first sorting** — critical always surfaces first\n3. **Evidence required** — no insight without at least 1 evidence item\n4. **Source layer attribution** — every evidence tagged with origin layer\n5. **Four-question standard** — what, why, action, risk_if_ignored\n6. **Flow C separation** — AI insights never write to Spine directly\n7. **Govern gate** — all autonomous actions require approval\n8. **Cache TTL 60s** — Entity 360 cached to prevent over-fetching\n\n## Trust Layer Contract\n\nEvery insight displayed in UI must show:\n\n- Severity badge with color coding\n- Confidence percentage with bar\n- Source layers (icons: Database, MessageSquare, Zap, Brain, Target)\n- Evidence chain (expandable)\n- Risk if ignored (red warning)\n- Recommended action (green panel)\n- Timestamp of assembly\n"}