Superseded

IntegrateWise Implementation Contract v1.1

Status: SUPERSEDED — absorbed into INTEGRATEWISE_ARCHITECTURE.md v2.1. Historical reference only.
Date: July 23, 2026
Supersedes: storage, identity, public MCP, and execution details in v1.0 where they conflict

This document does not add a new platform concept. It makes the frozen product
doctrine executable through one identity path, one public continuity contract,
one truth path, one projection path, and one governed execution path.

1. Product Contract

IntegrateWise has one product surface:

  1. Onboarding
  2. The role-specific User Workbench
  3. The Silent Twin, available contextually through the Four Buttons

The user does not inject context already held by the Spine Network. The Twin
inherits permitted active context, reads grounded evidence, prepares work, and
stays silent when it has no material contribution.

2. End-to-End Runtime

Configuration
→ Tenant-owned connections
→ Pipeline normalization
→ Adaptive Spine
→ Projection Engine
→ User Workbench
→ Silent Twin preparation
→ Governance approval
→ Hermes execution
→ Omni Router (tool execution)
→ Model Gateway (LLM inference)
→ Provider connector / MCP capability
→ Sync and outcome return
→ Pipeline promotion
→ Spine learning

The proactive loop is:

interaction_observation
→ contextual pattern
→ next-action candidate
→ Twin draft
→ governed proposal
→ approval
→ capability execution (Omni Router)
→ model inference (Model Gateway)
→ outcome
→ triage promotion when appropriate

Raw clicks are observations, not canonical truth. Only promoted, governed
outcomes may change the Adaptive Spine.

3. Identity Contract

  • Clerk is the browser identity authority.
  • Gateway validates the Clerk session and resolves tenant membership.
  • Customer Zero resolves to tenant iw-customer-zero.
  • AI and MCP consumers use the public OAuth-protected MCP boundary.
  • Provider OAuth credentials are tenant-owned and remain in the connector
    credential wall; they never enter a Workbench repository or AI prompt.
  • Descope browser-session paths are legacy compatibility only and must not be
    selected when Clerk is configured.

4. Spine Network Contract

The Spine is both storage and derivation:

SPINE = canonical storage + Projection Engine

Canonical storage

  • Neon Postgres owns canonical operational truth, relationships, lineage,
    governance artifacts, and promoted outcomes.
  • R2 owns files, documents, attachments, raw payloads, and immutable evidence.
  • Vectorize and AI Search own embeddings and retrieval indexes; they do not own
    canonical truth.

Bounded operational state

  • D1 owns active context, idempotency, projection snapshots, runtime state, and
    edge-operational indexes.
  • KV owns short-lived hot projections, sessions, connector status, and
    invalidation state.
  • D1 and KV are never independent systems of record.

Derivation

The Projection Engine is part of the Spine computation layer. It owns:

  • role- and permission-scoped KPI computation;
  • composition across canonical entities, signals, memory, documents, and
    attachments;
  • projection caching and invalidation;
  • the sole SharedWorkbench response contract.

The Workbench never queries provider-specific data models and never constructs
its own KPI truth.

5. Write Authority

  • Pipeline promotion is the sole canonical Spine writer.
  • The Twin has read access to permitted Spine context and may create drafts or
    proposals only.
  • The Workbench submits observations and mutations through Gateway.
  • No browser component, Twin runtime, MCP tool, connector, or projection
    component writes Neon directly.
  • Source-system actions require an immutable plan, policy evaluation, explicit
    authority, and an approval token.

6. Public MCP Contract

The public IW Spine Tools MCP exposes exactly these 19 semantic tools:

  1. get_my_continuity
  2. get_active_context
  3. get_my_focus
  4. get_context
  5. get_changes
  6. get_related
  7. get_history
  8. get_commitments
  9. get_decisions
  10. get_permitted_memory
  11. get_relevant_knowledge
  12. ask_twin
  13. assign_twin
  14. get_prepared_work
  15. get_available_actions
  16. prepare_action
  17. get_action_plan
  18. approve_action
  19. store_in_spine

The broader MCP Pool and capability registries remain internal. Context relay,
agent handoff, provider operations, transport details, raw table access, and
connector implementation tools are not public MCP tools.

The same 19 tools back two public packages:

  • IW-Spine-Network Plugin for plugin marketplaces/directories, with an
    MCP-backed app, focused sandboxed UI resources and workflow skills;
  • IW-Spine-Network MCP for MCP marketplaces/registries, with the remote
    server, optional MCP App UI resources, text/JSON fallback and browser
    Workbench launch.

UI resources do not add public tools. An embedded widget may communicate only
through the host's declared MCP App bridge. It cannot access the host DOM,
cookies, app credentials, Neon, provider credentials or internal MCP Pool.

7. Read and Projection Path

Workbench or AI consumer
→ Gateway
→ Projection Engine / public Spine MCP
→ Neon canonical truth + R2 evidence + retrieval indexes
→ D1/KV bounded projection cache
→ SharedWorkbench or semantic tool result

Projection cache misses may return an explicit partial-evidence state. They may
not silently replace live tenant data with demo seed data.

8. Governed Execution Path

Twin or user intent
→ capability resolution
→ immutable execution plan
→ Governance policy and evidence check
→ explicit human approval when required
→ approval token
→ Hermes
→ provider connector / MCP capability
→ source-system result
→ Pipeline normalization
→ promoted outcome in Neon
→ projection invalidation

Gateway and UI code must not invoke provider APIs directly after approval.
Hermes is the only coordinator of approved external execution.

9. Repository Boundaries

  • apps/web: App Router Workbench; only Gateway SDK and product contracts.
  • services/gateway: public control boundary, identity, tenant resolution,
    routing, and projection entry.
  • services/mcp-connector: exact public 19-tool semantic Spine MCP.
  • public package/app resources: IW-Spine-Network Plugin and MCP manifests,
    focused widgets, OAuth metadata and Workbench launch/configuration.
  • services/mcp-pool: internal capability registry and routing.
  • services/pipeline: normalization, triage, promotion, and canonical writes.
  • services/spine: canonical Neon read model and internal Spine operations.
  • packages/projection-engine: sole SharedWorkbench composer.
  • services/govern / services/hermes: authority decision and execution.
  • packages/model-gateway: Model Gateway — routes LLM inference to llama.cpp, HF, OpenAI, or any OpenAI-compatible provider.
  • packages/omni-router: Omni Router — provider-agnostic tool execution layer for any agent.
  • connector services: provider credentials, synchronization, and source-system
    transport.

10. Stop-Ship Invariants

A release is not aligned if any of the following is true:

  • the browser selects Descope while Clerk is configured;
  • the public MCP lists anything other than the 19 tools above;
  • the Plugin claims automatic inheritance of other host-app credentials or the
    MCP lane omits its standalone browser Workbench/fallback path;
  • a UI or Twin route writes Neon directly;
  • D1 is described or used as canonical business truth;
  • failed live projections silently become demo data;
  • an approved action bypasses Hermes;
  • a provider connector is copied into a product repository;
  • the user must explain context already present in the Spine Network;
  • L1/L2/L4/L7 appear as user-facing product navigation.