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