{"slug":"architecture/MARKETPLACE_CHANNELS_AND_DATA_FLOW_SPEC","title":"Marketplace Channels, Onboarding and Data Flow","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/MARKETPLACE_CHANNELS_AND_DATA_FLOW_SPEC.mdx","bytes":32158,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n**Status:** Proposed\n**Document type:** Specification\n**Authority:** Subordinate to [`INTEGRATEWISE_ARCHITECTURE.md`](../../architecture/INTEGRATEWISE_ARCHITECTURE.md)\n**Canonical sections implemented:** §9 (Four flows) · §10 (Capability, Governance, Hermes) · §15 (Profiles, channels, host-aware runtime) · §16 (Public boundary)\n**Owner:** Product + Platform\n**Version:** 1.0\n**Last verified against:** HEAD `d941a422`\n**Last verified date:** 2026-07-31\n**Supersedes:** none\n\n> This document adds implementation precision. It does not redefine kernel vocabulary,\n> ownership boundaries, truth authority, runtime ordering or governance invariants. Where it\n> appears to, the canonical architecture wins.\n\n---\n\n## 1. Purpose\n\nTwo marketplaces distribute IntegrateWise. This document specifies what is published to each,\nhow a user onboards through each, what they can do once inside, and — the part that is most\noften got wrong — **exactly how data entering through each channel is classified into Flow A,\nB, C or D.**\n\nThe governing claim it exists to protect:\n\n> Distribution channels change where the product renders and where identity comes from.\n> They never change where truth lives, what may write it, or what requires approval.\n\n---\n\n## 2. Two channels, one product\n\n| | **MCP Marketplace** | **Plugin Marketplace** |\n| ---------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| Published artifact | **IW-Spine-Network MCP** — remote server, exact 19-tool manifest, optional UI resources | **IW-Spine-Network Plugin** — MCP-backed app, focused UI resources, workflow skills |\n| Listed in | MCP registries and directories | Plugin directories and AI app stores |\n| Entry channel | `mcp_workbench` | `plugin_host` |\n| Identity source | IntegrateWise OAuth, initiated from the registry | Host installation grant |\n| Where UI renders | IntegrateWise browser Workbench | Embedded surface **inside the host** |\n| Who supplies inference | IntegrateWise Twin runtime | **The host's model** |\n| First connection | Chosen in the Workbench after landing | **Host-declared, runtime-confirmed capability context.** Credentials stay in the host trust boundary; where the host cannot supply a capability, the user creates an explicit IntegrateWise connection |\n| Navigation | Full sidebar | Constrained — the host owns the frame |\n\nThere is a third distribution — **direct activation into the browser Workbench** — which\nuses the same Gateway, the same contract and the same state machine, differing only in that\nidentity and workspace come from IntegrateWise directly. It is listed here so that\n\"marketplace\" is never mistaken for \"the only way in.\"\n\nEverything beneath those eight rows is identical: the same Gateway, the same Spine, the same\nProjection Engine, the same governance path, the same 19 tools. Both artifacts are **channel\npackages bound to one public contract** — never a different backend.\n\n> **IntegrateWise Workbench runs on IW-Spine-Network.**\n\n**Installing does not clone Customer Zero.** Activation resolves or creates an isolated\ncustomer tenant and applies the Customer Zero-proven reference configuration. Customer Zero\ndata, credentials, memory, cache, queues and audit never cross that boundary.\n\n---\n\n## 3. Go-to-market alignment\n\nThe commercial motion is **category-led, activation-assisted, proof-gated**. Marketplaces\nserve the second word, not the first.\n\n| The channel does | The channel does not |\n| -------------------------------------------------------------- | --------------------------------- |\n| Reduce time-to-first-connection to near zero | Define the category |\n| Put the product where the user's AI already is | Substitute for the platform story |\n| Prove the interop claim concretely — one install, many systems | Become the homepage |\n| Generate qualified activation, not just installs | Count installs as adoption |\n\n**North-star metric is unchanged: time to first approved governed outcome.** An install that\nnever reaches `active` is not progress, and a listing page that reports install counts is\nmeasuring the wrong thing. The channel-specific metric that matters is\n**install → `active` conversion**, and its failure modes are diagnosable by state (§4).\n\n**Claims discipline.** Marketplace listing copy is external copy and is bound by the claims\nregister: no connector counts, no benchmarks, no certifications, no logos without current\nevidence, and no implication of autonomous execution. The listing must state that\nconsequential action requires human approval — that is the differentiator, and understating\nit to look more capable inverts the positioning.\n\n---\n\n## 4. Onboarding — one state machine, two entry paths\n\nBoth channels enter the same machine. This is the invariant that keeps the product one\nproduct:\n\n```\ninitiated → identity_required → workspace_required → consent_required\n → binding → hydrating → active\n ↘ degraded | revoked | failed\n```\n\nOnly the first two states differ by channel:\n\n| State | `mcp_workbench` | `plugin_host` |\n| -------------------- | ------------------------------------------------------------------ | ------------------------------------- |\n| `initiated` | User adds the MCP server from a registry | User installs the app in the host |\n| `identity_required` | IntegrateWise OAuth | Host installation grant |\n| `workspace_required` | Tenant from IntegrateWise identity | Host account or team → tenant binding |\n| `consent_required` | **Identical** — scope disclosed, reviewed, accepted | **Identical** |\n| `binding` | **Identical** — connection binding created, credentials referenced | **Identical** |\n| `hydrating` | **Identical** — Loader → Normalizer → Spine | **Identical** |\n| `active` | **Identical** — Workbench composed, capabilities resolved | **Identical** |\n\n**Fork the last four and you have two products that hydrate differently.** `consent_required`\nis a governance gate; if a channel skips it, that channel has no consent record and no\ndefensible scope disclosure. A missing state-machine binding must fail closed with an explicit\nreason — never degrade to a direct write.\n\n### 4.1 What the user sees, per channel\n\n**MCP Marketplace.** Add the server → authorise IntegrateWise → land in the browser\nWorkbench → pick a first system to connect → watch it hydrate → open the Workbench composed\nfor the role → approve one action.\n\n**Plugin Marketplace.** Install in the host → grant → tenant resolved from the host account →\nconsent to scope → the embedded surface appears in-conversation → the host's model can now\ncall the 19 tools → the first approval happens **in the embedded surface, server-enforced**.\n\n---\n\n## 5. Use — what each channel is good at\n\n| | MCP Marketplace | Plugin Marketplace |\n| ---------- | ------------------------------------------------------------ | ---------------------------------------------------------------- |\n| Best for | Deep work in one surface; full Workbench fidelity | Answering in the flow of an existing conversation |\n| Twin | IntegrateWise's own runtime; Silence Law enforced in-product | Host model reasons; Silence Law enforced **server-side** |\n| Strength | Complete role composition, canvases, full navigation | Zero context-switch; the user is already there |\n| Constraint | User must leave their AI to work | Reduced surface; host owns the frame |\n| Deep link | — | Escapes to the full Workbench for anything the panel cannot hold |\n\nThe Twin's enforcement point moving is the single most important design consequence of the\nplugin channel. In `mcp_workbench` the reasoning runtime is ours. In `plugin_host` it is not\n— so **the approval boundary must be enforced at the Gateway, never in UI.** A host model\ncannot be trusted to respect a client-side gate. The plugin channel is the case that proves\nwhy the rule must hold everywhere.\n\n---\n\n## 6. Data flow — MCP Marketplace channel\n\n```\nIntegrateWise-managed connector (Integration Manager / credential wall)\n ↓ provider objects, documents, events\n Loader RawObservation { sourcePlane: \"integratewise\" }\n ↓\n Normalizer Path validate · map · resolve identity · dedupe · provenance\n ↓\n Governed Spine Writer ← the only canonical commit\n ↓\n Canonical Spine (Neon)\n ↓\n Enrichment pass chunk → embed → link → concepts → embedding_id\n ↓\n Projection Engine → Spine Cache → Workbench + Twin\n```\n\nStraightforward: IntegrateWise owns the connection, so it owns the ingestion. Credentials sit\nin the credential wall; the Spine stores opaque references only.\n\n---\n\n## 7. Data flow — Plugin Marketplace channel\n\nThis is the path with the constraint that must not be forgotten.\n\n**IntegrateWise may not enumerate the host's connected apps, may not read another app's OAuth\ntoken, may not invoke unrelated host apps, and may not bypass the host's permission or\nconfirmation model.** The host orchestrates its own apps.\n\nHost capability therefore enters through five explicit mechanisms, and **declared is never\nproof of available** — every one is validated at runtime, and only `confirmed` may be routed\nto.\n\n```\n ① host-declared capability context at invocation\n ② tool-result handoff — host invokes its app, passes evidence to an IW tool\n ③ workflow orchestration — host selects both its apps and IW tools\n ④ explicit IntegrateWise connection where the host lacks the capability\n ⑤ installation manifest / policy declaration → still validated at runtime\n ↓\n Loader RawObservation { sourcePlane: \"host\", host: \"chatgpt\", … }\n ↓\n Normalizer Path same pipeline, same provenance rules\n ↓\n Governed Spine Writer\n ↓\n Canonical Spine (Neon) → enrichment → Spine Cache → embedded surface\n```\n\nTwo consequences worth stating plainly:\n\n**A host tool result is an observation, not truth.** It arrives with `sourcePlane: \"host\"`,\nretains host and provider, and becomes canonical only through the Normalizer and the governed\nwrite. The Workbench does not treat a provider payload as fact because the host happened to\nhold a token.\n\n**Spine completes what the host cannot reach.** If the host has mail but not CRM, the CRM\ncontext comes from IntegrateWise's canonical state or its own governed connector — not by\nbrokering to another host. There is no agent-to-agent credential exchange, and none is needed.\n\n---\n\n## 8. How data from AI tools flows\n\n\"Data from the AI\" is three different things with three different destinations. Conflating\nthem is the most common and most consequential modelling error in this area.\n\n| What the AI produced | What it is | Destination | May become truth? |\n| ------------------------------------------------------------------ | -------------- | ------------------------------------------- | ----------------------------------------------------------------- |\n| **Tool result** — the host invoked an app and got records back | Evidence | **Flow A or B**, via Loader → Normalizer | Yes, through governed promotion |\n| **Model output** — reasoning, summary, conclusion, proposed memory | Interpretation | **Flow C** | **Never directly.** Triage classifies; the promotion gate governs |\n| **Requested action** — \"send this email\", \"update this record\" | Intent | **Not a flow.** The governed execution path | Its _outcome_ re-enters as Flow A/B |\n\n### 8.0 Flow C is the whole cognitive interaction, not just the output\n\nFlow C is wider than \"what the AI said.\" It carries the entire human–AI exchange:\n\n**Human to AI** — prompts, instructions, questions, corrections, decisions expressed\nconversationally, delegated tasks, requested actions, user-supplied observations.\n\n**AI generated** — responses, summaries, recommendations, analysis, plans, drafts,\nclassifications, inferred risks, proposed next actions, generated tool parameters, candidate\nmemory, synthetic conclusions.\n\n**Runtime cognitive state** — conversation thread, active context, agent working memory,\nreasoning checkpoints, tool-call intent and interpretation, uncertainty, confidence,\ncontradictions, evidence selection, task progress.\n\n**A tool call is three things:**\n\n```\ntool request → Flow C the model's intent\nprovider result → Flow A or B what came back\nmodel interpretation → Flow C what the model concluded\n```\n\n_\"Fetch open opportunities\"_ is Flow C. The returned opportunity objects are Flow A. _\"Three\nare at risk because no next meeting is scheduled\"_ is Flow C again — and stays a candidate\neven if it is correct.\n\n### 8.0a Where Flow C material goes\n\n| Branch | Material | Destination | Widens by |\n| ------ | --------------------------------- | --------------------- | ---------------------------------------------------- |\n| **C1** | Current thread state | Conversational memory | Never — decays |\n| **C2** | Tool outcomes, learned routing | Agent memory | Triage only |\n| **C3** | User preference or private note | Personal memory | **Never** — cited by its owner only |\n| **C4** | Institutionally useful conclusion | Org-memory candidate | Triage → staging → human approval |\n| **C5** | Extracted canonical fact | Fact candidate | Evidence + schema + conflict check → governed writer |\n| **C6** | Proposed external action | Action proposal | Policy → approval token → Hermes or host route |\n\n**C5 deserves care.** \"The renewal date is 30 September 2026, extracted from the signed\ncontract\" is not a fact because a model read it correctly. It becomes canonical only after the\noriginal artifact is retained, the source location identified, the canonical entity resolved,\nthe field schema validated, provenance attached and a conflict check completed. Then a\ngoverned writer commits it.\n\n### 8.1 The host's model output is Flow C\n\nWhen ChatGPT or Claude reasons over IntegrateWise data and reaches a conclusion, that\nconclusion is **Flow C — a candidate**. It does not become organisational truth because a\ncapable model asserted it, and it does not become truth because its confidence was high.\n\nThis is the Authority Law at the channel boundary: _confidence increases trust; confidence\nnever grants authority._ The plugin channel makes it concrete — the reasoning is rented, the\ntruth is owned, and the gate between them is ours.\n\n### 8.2 An action is not a flow\n\nAn action request enters the execution path, not the ingestion partitions:\n\n```\nintent → capability resolution → immutable plan → policy + evidence\n → approval token → route resolution\n → execute (host-native tool OR IntegrateWise Capability Fabric)\n → receipt → Loader → Normalizer → reconciliation → promotion\n```\n\nThe execution _route_ may be host-native. The governance _route_ never varies. Both routes\nproduce the same canonical receipt structure, and an outcome of `unknown` enters\nreconciliation rather than being retried.\n\n---\n\n## 8.3 Read and write routing\n\n**Read precedence.** Confirmed host-native live capability → Spine canonical context →\nIntegrateWise-managed live connector → Spine Cache or historical evidence → request a new\nconnection → unavailable.\n\nRoutes combine in one answer. Mail may be host-native while CRM comes from an IntegrateWise\nconnector and continuity comes from Spine history — each retaining its own provenance and\nfreshness. **A host-local answer must never claim cross-system completeness.**\n\n**Write precedence.** Resolve canonical target → determine effective policy → create proposal\n→ determine allowed routes → human approval → prefer confirmed host-native route where\npermitted → otherwise Capability Fabric → capture receipt → normalise → reconcile → rehydrate.\n\nThe host may execute the provider call. IntegrateWise still owns target resolution, policy\nevaluation, the proposal, the approval requirement, the receipt contract, reconciliation and\ncanonical promotion. **The execution route varies; the governance route never does.**\n\n## 8.4 Activation envelope\n\n```ts\ninterface MarketplaceActivation {\n installationId: string;\n distribution: \"mcp_marketplace\" | \"plugin_marketplace\" | \"direct\";\n host: string;\n actor: { externalPrincipalId: string; canonicalUserId?: string };\n scope: {\n tenantId: string;\n tenantAccountId: string;\n workspaceId: string;\n spineNetworkId: string;\n };\n capabilities: Array<{\n capabilityId: string;\n source: \"host\" | \"integratewise\";\n availability: \"confirmed\" | \"declared\" | \"unknown\";\n effect: \"read\" | \"derive\" | \"mutate\";\n scopes: string[];\n }>;\n connections: Array<{\n providerKey: string;\n hostConnectionRef?: string;\n integratewiseConnectionId?: string;\n routingPreference: \"host-first\" | \"integratewise-first\" | \"policy-decides\";\n }>;\n activationState:\n | \"initiated\"\n | \"identity_required\"\n | \"workspace_required\"\n | \"consent_required\"\n | \"binding\"\n | \"hydrating\"\n | \"active\"\n | \"degraded\"\n | \"revoked\"\n | \"failed\";\n}\n```\n\nActivation must create or resolve: Actor · Tenant · TenantAccount · Workspace · Membership ·\nRole and permissions · SpineNetwork · MarketplaceInstallation · HostBinding · ConnectorBinding\n· SpineConnection · CredentialReference · CapabilityManifest · PolicySet · RoutingPreference ·\nSchemaBindingSet · HydrationJob · ProjectionManifest.\n\n## 9. Flow A / B / C / D mapping\n\n### 9.1 Flow D runs first\n\nFlow D is not a peer of A, B and C — it is their **precondition**. Nothing can be classified,\nscoped or written until the authority context exists.\n\n```\nINSTALL / CONNECT\n ↓\n FLOW D identity · tenant · workspace · membership · role\n consent · connection binding · credential reference\n capability grants · policy · runtime bindings\n ↓\n authority context resolved\n ↓\n FLOW A · FLOW B · FLOW C ← may now be classified and routed\n```\n\nAn observation arriving before Flow D has resolved has no tenant, and a record without a\ntenant cannot be written. It fails closed.\n\n### 9.2 The complete mapping\n\n| Event in either channel | Flow | Canonical boundary |\n| -------------------------------------------- | ------------------ | ------------------------------------------------------------ |\n| **Installation and identity** | | |\n| Marketplace install initiated | **D** | Installation record; no business data yet |\n| Identity granted (IW OAuth or host grant) | **D** | Principal resolved to canonical identity |\n| Tenant / workspace bound | **D** | Tenant scope established — required by everything downstream |\n| Consent to data scope | **D** | Governance record; scope disclosed and accepted |\n| Connection binding created | **D** | `connector_binding_id` + opaque credential reference |\n| Capability grants resolved | **D** | Which operations exist for this principal, in this profile |\n| **Ingestion** | | |\n| CRM/ticket/deal objects from an IW connector | **A** | Deterministic normalisation → governed writer |\n| Structured records inside a host tool result | **A** | Same path; `sourcePlane: \"host\"` retained |\n| Emails, messages, meetings, transcripts | **B** | Raw artifact preserved; extracted meaning keeps lineage |\n| Documents and attachments | **B** | Bytes to R2; canonical record references them |\n| Unstructured host tool output | **B** | Same path; host and provider retained on evidence |\n| **AI-produced** | | |\n| Host model reasoning or summary | **C** | Never writes truth; Triage proposes |\n| Twin proposal or draft | **C** | Candidate; requires approval to become anything |\n| Candidate memory or knowledge | **C** | `staging`; usable by the Twin only once approved |\n| Agent working state, learned routing | **C** | Agent Memory; evidence, not truth |\n| Conversational session context | **C** | Decays; never promoted directly |\n| **Execution and return** | | |\n| Approved action executing | _(execution path)_ | Capability → Governance → Hermes or host-native |\n| Execution receipt | **B** | Evidence of what happened |\n| Provider outcome re-ingested | **A** _(or B)_ | Normalised, reconciled, promoted |\n| Reconciled canonical change | **A** | New canonical state; projections invalidated |\n\n### 9.3 The rule in one line per flow\n\n- **Flow A** — structured operational state. Deterministic normalisation prepares; governed writers commit.\n- **Flow B** — evidence. Raw artifacts preserved with provenance; promotion is governed.\n- **Flow C** — interpretation. **Never writes operational truth.** Triage classifies; the gate governs.\n- **Flow D** — authority and binding. Runs first; governed configuration writers only. Not a business-data partition.\n\n---\n\n## 10. Invariants for both channels\n\nA channel implementation is non-conformant if any of these is true:\n\n1. The public MCP lists anything other than the exact 19 tools\n2. Onboarding skips `consent_required`, or a missing state-machine binding degrades to a direct write\n3. Host capability is routed to on `declared` availability without runtime confirmation\n4. IntegrateWise enumerates, or attempts to invoke, host apps it was not explicitly given\n5. A host credential is stored by IntegrateWise absent a separate IntegrateWise connection\n6. The same provider is called through both host and IntegrateWise by default\n7. Host model output is written as canonical truth\n8. A material write executes without proposal, policy decision, receipt and reconciliation — **on any route**\n9. The approval gate is enforced client-side in a host surface\n10. An answer claims cross-system completeness without reporting `canonical`, or naming what it could not see\n11. Installation clones Customer Zero data, credentials, memory, cache, queues or audit\n12. Listing copy claims autonomous execution, or omits that consequential action requires approval\n\n---\n\n## 11. Acceptance criteria\n\n**Onboarding.** Both channels reach `active` through the same state machine · `consent_required`\nis enforced and produces a scope record in both · a missing binding returns an explicit failure,\nnever a silent fallback · tenant isolation holds across two installs from the same host account.\n\n**Channel parity.** The 19-tool listing is byte-identical across profiles · the same domain\npackages serve both channels · a host adapter contains no policy and no canonical schema.\n\n**Host constraint.** A host-declared-but-unavailable capability falls back deterministically ·\na confirmed host capability is used in preference to a duplicate IntegrateWise connector ·\ncontext for a system the host cannot reach is supplied by Spine completion without that system\nbeing connected to the host.\n\n**Flow classification.** A host tool result is stored as `RawObservation` with `sourcePlane:\n\"host\"` and normalises with provenance intact · host model output lands in Flow C and cannot\nreach `approved` without an approver identity · an approved action's outcome re-enters as\nFlow A/B and reconciles.\n\n**GTM.** Install → `active` conversion is instrumented per channel · time to first approved\ngoverned outcome is measured from `active`, not from install.\n\n### 11.1 Funnel mapped to runtime state\n\nThe commercial funnel and the activation state machine are the same events. Instrument once,\nreport twice.\n\n| GTM stage | Runtime evidence |\n| ------------------- | -------------------------------------------------------------- |\n| Impression | Listing viewed |\n| Install | MarketplaceInstallation created |\n| Activation started | `initiated` |\n| Identity completed | Canonical actor resolved |\n| Workspace activated | Tenant · workspace · SpineNetwork resolved |\n| First connection | Confirmed host or IntegrateWise binding |\n| Hydration started | Initial sync job created |\n| **First value** | First `canonical`, or explicitly disclosed `partial`, response |\n| Engaged | Repeated continuity and context use |\n| **Governed value** | First proposal approved |\n| **Closed loop** | First execution reconciled into the Spine |\n| Expanded | Additional provider connected |\n| Retained | Recurring cross-system use and continuity retrieval |\n\nPrimary activation metric: **first grounded continuity answer from a resolved workspace, with\nprovenance and disclosed completeness.** Not \"installed.\"\nPrimary value metric: **first governed action executed and reconciled into canonical state.**\n\n---\n\n## 12. Current state\n\nPer the canonical architecture Part III, dated 2026-07-31:\n\n| Element | State |\n| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |\n| Channel model, onboarding machine, flow mapping | **Defined** |\n| Marketplace installation state machine | **Implemented** — Gateway now routes to it; consent gate reachable |\n| Public 19-tool contract | **Implemented** — deployment and list verification pending |\n| IW-Spine-Network MCP package | **Partial** — listing, fallback and browser launch not established |\n| IW-Spine-Network Plugin package | **Missing** — no host-submission artifact or clean-install evidence |\n| Canonical persistence behind both channels | **Broken** — see architecture **S0**. Canonical writes are skipped and cache writes are reported as success |\n| Hermes execution | **Unreachable** — no inbound binding |\n\n**Neither channel can be submitted for listing until S0 is repaired.** A marketplace install\nthat hydrates into a cache which reports itself as the record is worse than no install: it\nproduces a confident, ungrounded product experience and no durable customer value. The\nordered closure sequence is architecture Appendix K, steps 0–15.\n\n---\n\n**Related:** [Architecture §9, §10, §15, §16](../../architecture/INTEGRATEWISE_ARCHITECTURE.md) ·\n[Host-Aware Continuity Runtime Spec](../../architecture/HOST_AWARE_CONTINUITY_RUNTIME_SPEC.md) ·\n[IW-Spine-Network Plugin and MCP Marketplace Contract](../../architecture/IW_SPINE_NETWORK_PLUGIN_AND_MCP_MARKETPLACE_CONTRACT.md) ·\n[GTM Canon](../../commercial/09-gtm/00-current-gtm-canon.md)\n"}