{"slug":"architecture/IMPLEMENTATION_CONTRACT_v1.1","title":"IntegrateWise Implementation Contract v1.1","section":"architecture","sectionLabel":"Architecture","status":"superseded","type":"document","path":"architecture/IMPLEMENTATION_CONTRACT_v1.1.mdx","bytes":7913,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n**Status:** SUPERSEDED — absorbed into INTEGRATEWISE_ARCHITECTURE.md v2.1. Historical reference only.  \n**Date:** July 23, 2026  \n**Supersedes:** storage, identity, public MCP, and execution details in v1.0 where they conflict\n\nThis document does not add a new platform concept. It makes the frozen product\ndoctrine executable through one identity path, one public continuity contract,\none truth path, one projection path, and one governed execution path.\n\n## 1. Product Contract\n\nIntegrateWise has one product surface:\n\n1. Onboarding\n2. The role-specific User Workbench\n3. The Silent Twin, available contextually through the Four Buttons\n\nThe user does not inject context already held by the Spine Network. The Twin\ninherits permitted active context, reads grounded evidence, prepares work, and\nstays silent when it has no material contribution.\n\n## 2. End-to-End Runtime\n\n```text\nConfiguration\n→ Tenant-owned connections\n→ Pipeline normalization\n→ Adaptive Spine\n→ Projection Engine\n→ User Workbench\n→ Silent Twin preparation\n→ Governance approval\n→ Hermes execution\n→ Omni Router (tool execution)\n→ Model Gateway (LLM inference)\n→ Provider connector / MCP capability\n→ Sync and outcome return\n→ Pipeline promotion\n→ Spine learning\n```\n\nThe proactive loop is:\n\n```text\ninteraction_observation\n→ contextual pattern\n→ next-action candidate\n→ Twin draft\n→ governed proposal\n→ approval\n→ capability execution (Omni Router)\n→ model inference (Model Gateway)\n→ outcome\n→ triage promotion when appropriate\n```\n\nRaw clicks are observations, not canonical truth. Only promoted, governed\noutcomes may change the Adaptive Spine.\n\n## 3. Identity Contract\n\n- Clerk is the browser identity authority.\n- Gateway validates the Clerk session and resolves tenant membership.\n- Customer Zero resolves to tenant `iw-customer-zero`.\n- AI and MCP consumers use the public OAuth-protected MCP boundary.\n- Provider OAuth credentials are tenant-owned and remain in the connector\n  credential wall; they never enter a Workbench repository or AI prompt.\n- Descope browser-session paths are legacy compatibility only and must not be\n  selected when Clerk is configured.\n\n## 4. Spine Network Contract\n\nThe Spine is both storage and derivation:\n\n```text\nSPINE = canonical storage + Projection Engine\n```\n\n### Canonical storage\n\n- Neon Postgres owns canonical operational truth, relationships, lineage,\n  governance artifacts, and promoted outcomes.\n- R2 owns files, documents, attachments, raw payloads, and immutable evidence.\n- Vectorize and AI Search own embeddings and retrieval indexes; they do not own\n  canonical truth.\n\n### Bounded operational state\n\n- D1 owns active context, idempotency, projection snapshots, runtime state, and\n  edge-operational indexes.\n- KV owns short-lived hot projections, sessions, connector status, and\n  invalidation state.\n- D1 and KV are never independent systems of record.\n\n### Derivation\n\nThe Projection Engine is part of the Spine computation layer. It owns:\n\n- role- and permission-scoped KPI computation;\n- composition across canonical entities, signals, memory, documents, and\n  attachments;\n- projection caching and invalidation;\n- the sole `SharedWorkbench` response contract.\n\nThe Workbench never queries provider-specific data models and never constructs\nits own KPI truth.\n\n## 5. Write Authority\n\n- Pipeline promotion is the sole canonical Spine writer.\n- The Twin has read access to permitted Spine context and may create drafts or\n  proposals only.\n- The Workbench submits observations and mutations through Gateway.\n- No browser component, Twin runtime, MCP tool, connector, or projection\n  component writes Neon directly.\n- Source-system actions require an immutable plan, policy evaluation, explicit\n  authority, and an approval token.\n\n## 6. Public MCP Contract\n\nThe public IW Spine Tools MCP exposes exactly these 19 semantic tools:\n\n1. `get_my_continuity`\n2. `get_active_context`\n3. `get_my_focus`\n4. `get_context`\n5. `get_changes`\n6. `get_related`\n7. `get_history`\n8. `get_commitments`\n9. `get_decisions`\n10. `get_permitted_memory`\n11. `get_relevant_knowledge`\n12. `ask_twin`\n13. `assign_twin`\n14. `get_prepared_work`\n15. `get_available_actions`\n16. `prepare_action`\n17. `get_action_plan`\n18. `approve_action`\n19. `store_in_spine`\n\nThe broader MCP Pool and capability registries remain internal. Context relay,\nagent handoff, provider operations, transport details, raw table access, and\nconnector implementation tools are not public MCP tools.\n\nThe same 19 tools back two public packages:\n\n- **IW-Spine-Network Plugin** for plugin marketplaces/directories, with an\n  MCP-backed app, focused sandboxed UI resources and workflow skills;\n- **IW-Spine-Network MCP** for MCP marketplaces/registries, with the remote\n  server, optional MCP App UI resources, text/JSON fallback and browser\n  Workbench launch.\n\nUI resources do not add public tools. An embedded widget may communicate only\nthrough the host's declared MCP App bridge. It cannot access the host DOM,\ncookies, app credentials, Neon, provider credentials or internal MCP Pool.\n\n## 7. Read and Projection Path\n\n```text\nWorkbench or AI consumer\n→ Gateway\n→ Projection Engine / public Spine MCP\n→ Neon canonical truth + R2 evidence + retrieval indexes\n→ D1/KV bounded projection cache\n→ SharedWorkbench or semantic tool result\n```\n\nProjection cache misses may return an explicit partial-evidence state. They may\nnot silently replace live tenant data with demo seed data.\n\n## 8. Governed Execution Path\n\n```text\nTwin or user intent\n→ capability resolution\n→ immutable execution plan\n→ Governance policy and evidence check\n→ explicit human approval when required\n→ approval token\n→ Hermes\n→ provider connector / MCP capability\n→ source-system result\n→ Pipeline normalization\n→ promoted outcome in Neon\n→ projection invalidation\n```\n\nGateway and UI code must not invoke provider APIs directly after approval.\nHermes is the only coordinator of approved external execution.\n\n## 9. Repository Boundaries\n\n- `apps/web`: App Router Workbench; only Gateway SDK and product contracts.\n- `services/gateway`: public control boundary, identity, tenant resolution,\n  routing, and projection entry.\n- `services/mcp-connector`: exact public 19-tool semantic Spine MCP.\n- public package/app resources: IW-Spine-Network Plugin and MCP manifests,\n  focused widgets, OAuth metadata and Workbench launch/configuration.\n- `services/mcp-pool`: internal capability registry and routing.\n- `services/pipeline`: normalization, triage, promotion, and canonical writes.\n- `services/spine`: canonical Neon read model and internal Spine operations.\n- `packages/projection-engine`: sole `SharedWorkbench` composer.\n- `services/govern` / `services/hermes`: authority decision and execution.\n- `packages/model-gateway`: Model Gateway — routes LLM inference to llama.cpp, HF, OpenAI, or any OpenAI-compatible provider.\n- `packages/omni-router`: Omni Router — provider-agnostic tool execution layer for any agent.\n- connector services: provider credentials, synchronization, and source-system\n  transport.\n\n## 10. Stop-Ship Invariants\n\nA release is not aligned if any of the following is true:\n\n- the browser selects Descope while Clerk is configured;\n- the public MCP lists anything other than the 19 tools above;\n- the Plugin claims automatic inheritance of other host-app credentials or the\n  MCP lane omits its standalone browser Workbench/fallback path;\n- a UI or Twin route writes Neon directly;\n- D1 is described or used as canonical business truth;\n- failed live projections silently become demo data;\n- an approved action bypasses Hermes;\n- a provider connector is copied into a product repository;\n- the user must explain context already present in the Spine Network;\n- L1/L2/L4/L7 appear as user-facing product navigation.\n"}