MarketplaceCatalogService

Target

This page describes intended behaviour or structure. No implementation is claimed unless a section is explicitly marked Current implementation or Evidence.

Bounded context	BC-27 Marketplace Catalog & Distribution
Platform / plane	Marketplace / Capability & Tools
Deployment granularity	module of host · host MarketplaceHost
Status	target · ConnectSoft.Factory.Marketplace.Catalog
Built from	connectsoft-microservice · libraries: connectsoft-extensions-saas-abstractions, connectsoft-extensions-messaging-model, connectsoft-extensions-persistence-model-nhibernate, connectsoft-extensions-query-model
Decisions	ADR-0021, ADR-0023
Traceability	FR-02 FR-04 FUX-01 FUX-03 NFR-13 XL-03 XL-15

Purpose and responsibilities

MarketplaceCatalogService distributes what the Factory already qualified. A listing points at a Published release (agent, skill, workflow, tool, model profile, template, blueprint) or an operated product, carries its evaluation evidence and provenance, declares compatibility (Factory editions, template versions, topologies, model profiles required) and dependencies on other listings, and goes through Draft, InReview and Listed — public visibility needs a certified publisher and a Platform admin approval of class publication. Installation into a tenant or project checks the entitlement and the tenant's policy, then creates a scoped reference to the release in the tenant's asset registry: nothing is copied, and the tenant's own policy may restrict the installed asset further. A newer Published release offers an update; a Deprecated release delists; a Revoked one delists and notifies.

It absorbs the June-2026 catalog, search, version, compatibility, installation, dependency-resolution and marketplace-publishing rows.

Context and boundaries

flowchart LR
    S["MarketplaceCatalogService"]
    AgentCardService["AgentCardService"] -->|grpc| S
    StudioBff["StudioBff"] -->|sync-http| S
    S -->|grpc| AgentRegistryService["AgentRegistryService"]
    S -->|grpc| LicenseService["LicenseService"]
    S -->|grpc| PolicyEngineService["PolicyEngineService"]
    S -->|grpc| ArtifactService["ArtifactService"]
    S -. "ListingPublished" .-> E_ListingPublished(("event"))
    S -. "ListingStateChanged" .-> E_ListingStateChanged(("event"))
    S -. "ListingInstalled" .-> E_ListingInstalled(("event"))
    S -. "ListingRemoved" .-> E_ListingRemoved(("event"))

Hold "Alt" / "Option" to enable pan & zoom

Publication is BC-04's; the marketplace lists, it never publishes. Runs that pinned a snapshot keep running after a removal or revocation; new runs are refused by the registry. Agent cards expose listings for A2A discovery (ADR-0023).

Domain model

Listing — A marketplace listing of one asset or product: publisher, kind, the Published release it points to (never a copy), evaluation evidence and provenance references, compatibility (Factory editions, template versions, topologies), pricing reference (BC-28), visibility and state. (catalog entry)

Field	Type	Required	Description
listingId	guid	yes
tenantId	string	yes	Platform tenant for public listings; the publisher's tenant otherwise.
publisherId	guid	yes
kind	enum:ListingKind	yes
assetId	string	yes
releaseId	string	yes	Published release in BC-04 (or product release for operated products).
evidenceRef	string	yes	Evaluation record (ADR-0021).
compatibility	json	yes	editions, template versions, topologies, model profiles required
dependencies	json	yes	Other listings or asset releases required.
pricingRef	guid	no
visibility	enum:Visibility	yes
state	enum:ListingState	yes
documentRefs	json	yes	Description, screenshots, changelog as artifacts.
listedAt	datetime	no

Invariants:

• A listing references a Published release with evaluation evidence; a Deprecated or Revoked release delists automatically.
• A listing never copies an asset; installation is a scoped reference to the release in the installing tenant's registry.
• Public visibility needs Platform admin approval of the listing (publication class) and a certified publisher.

stateDiagram-v2
    Draft --> InReview : Submit
    InReview --> Listed : Approved
    InReview --> Draft : ChangesRequested
    Listed --> Suspended : PolicyOrEvidenceIssue
    Suspended --> Listed : Resolved
    Listed --> Delisted : ReleaseDeprecatedOrPublisherDelists

Hold "Alt" / "Option" to enable pan & zoom

Events: ListingPublished, ListingStateChanged · Tables: Listings, ListingDependencies · Repository: ListingRepository

Installation — The installation of a listing into a tenant (and optionally a project): the entitlement checked, the scoped release reference created in the tenant's asset registry, the version installed, and updates offered when the listing moves to a newer release. (catalog entry)

Field	Type	Required	Description
installationId	guid	yes
tenantId	string	yes
projectId	string	no
listingId	guid	yes
releaseId	string	yes
entitlementId	guid	no
state	enum:InstallationState	yes
installedBy	string	yes
installedAt	datetime	no
updateAvailableReleaseId	string	no

Invariants:

• Installation needs an entitlement (free listings have an implicit one) and the tenant's policy allow for the listing kind.
• Installing never changes the tenant's own assets; it adds a scoped reference that the tenant's policy may restrict further.

stateDiagram-v2
    Requested --> EntitlementChecked : EntitlementOk
    EntitlementChecked --> Installed : ReferenceCreated
    Installed --> Updating : UpdateAccepted
    Updating --> Installed : ReferenceUpdated
    Installed --> Removed : Remove
    Requested --> Failed : EntitlementMissingOrPolicyDeny

Hold "Alt" / "Option" to enable pan & zoom

Events: ListingInstalled, ListingRemoved · Tables: Installations · Repository: InstallationRepository

erDiagram
    Listing {
        guid listingId PK
        string tenantId
        guid publisherId
        enum_ListingKind kind
        string assetId
        string releaseId
        string evidenceRef
        json compatibility
        json dependencies
        guid pricingRef
        enum_Visibility visibility
        enum_ListingState state
        json documentRefs
        datetime listedAt
    }
    Installation {
        guid installationId PK
        string tenantId
        string projectId
        guid listingId
        string releaseId
        guid entitlementId
        enum_InstallationState state
        string installedBy
        datetime installedAt
        string updateAvailableReleaseId
    }

Hold "Alt" / "Option" to enable pan & zoom

Entities and value objects

None modelled

No entities or value objects are modelled for this item yet.

Data model and storage

Store	Role	Engine / profile	Tables
Marketplace store	primary	azure-sql / nhibernate-sqlserver	Listings, ListingDependencies, Installations

Table	Owner	Columns	Indexes
dbo.Listings	Listing	14	2
dbo.ListingDependencies	Listing	4	0
dbo.Installations	Installation	10	1

Full DDL: appendix.

APIs

Method	Path	Operation	Scope	Side effects	Idempotency	Gateway	Summary
GET	/factory/marketplace/listings	SearchListings	factory.marketplace.read	read	natural	GW-03	Search and browse listings by kind, text, compatibility with the caller's edition and template versions, publisher and rating.
GET	/factory/marketplace/listings/{listingId}	GetListing	factory.marketplace.read	read	natural	GW-03	One listing with release, evidence, provenance, compatibility, dependencies, pricing and documents.
POST	/factory/marketplace/listings	CreateListing	factory.marketplace.publish	shared-write	key-header	GW-03	Create a Draft listing for a Published release (certified publisher).
POST	/factory/marketplace/listings/{listingId}/submit	SubmitListing	factory.marketplace.publish	publication	natural	GW-03	Submit for review; public visibility needs Platform admin approval (publication class).
POST	/factory/marketplace/listings/{listingId}/install	InstallListing	factory.marketplace.install	shared-write	key-header	GW-03	Install into the caller's tenant or project: entitlement check, policy check, scoped release reference.
GET	/factory/marketplace/installations	ListInstallations	factory.marketplace.read	read	natural	GW-03	Installations in scope with available updates.
DELETE	/factory/marketplace/installations/{installationId}	RemoveInstallation	factory.marketplace.install	shared-write	natural	GW-03	Remove the scoped reference (runs using it keep their pinned snapshots).

gRPC service	Method	Streaming	Visibility	Side effects	Summary
Catalog	ResolveListing	none	internal	read	Resolve a listing to its Published release for the agent card and A2A discovery (ADR-0023).

Messages

Event	Topic	Scope / v	Aggregate	Consumers	Summary
ListingPublished	marketplace.listings.v1.listing-published	integration / 1	Listing	StudioBff, AuditService, AgentCardService, LicenseService	A listing is Listed and visible.
ListingStateChanged	marketplace.listings.v1.listing-state-changed	integration / 1	Listing	StudioBff, AuditService, LicenseService	A listing changed state (suspended, delisted, re-listed).
ListingInstalled	marketplace.installations.v1.listing-installed	integration / 1	Installation	AgentRegistryService, StudioBff, AuditService, LicenseService	A listing was installed or updated in a tenant.
ListingRemoved	marketplace.installations.v1.listing-removed	integration / 1	Installation	AgentRegistryService, StudioBff, AuditService, LicenseService	An installation was removed.

ListingPublished payload:

Field	Type	Required	Description
listingId	guid	yes
tenantId	string	yes
kind	enum:ListingKind	yes
assetId	string	yes
releaseId	string	yes
visibility	enum:Visibility	yes

ListingStateChanged payload:

Field	Type	Required	Description
listingId	guid	yes
tenantId	string	yes
fromState	enum:ListingState	yes
toState	enum:ListingState	yes
reason	string	no

ListingInstalled payload:

Field	Type	Required	Description
installationId	guid	yes
tenantId	string	yes
projectId	string	no
listingId	guid	yes
releaseId	string	yes

ListingRemoved payload:

Field	Type	Required	Description
installationId	guid	yes
tenantId	string	yes
listingId	guid	yes

Command	Handled by	Result events	Summary
CreateListing	Listing	—
SubmitListing	Listing	ListingPublished
InstallListing	Installation	ListingInstalled
RemoveInstallation	Installation	ListingRemoved

Event	Producer	Handler	Purpose
AssetReleasePublished	AgentRegistryService	OfferListingUpdate	A newer Published release offers a listing update and installation updates.
AssetReleaseDeprecated	AgentRegistryService	DelistOrFlag	Deprecated releases delist; installations are flagged.
AssetReleaseRevoked	AgentRegistryService	DelistAndNotify	Revoked releases delist immediately and installations are notified.
ApprovalDecided	RunControlService	ApplyListingApproval	Public listing approvals.
EntitlementGranted	LicenseService	ContinueInstallation	An entitlement allows an installation to proceed.

Workers and jobs

Worker	Trigger	Output events	Retry	Idempotency key	Summary
Indexer	event	—	fixed	listingId + version	Maintains the search index of listings (text, kind, compatibility, publisher, rating) from listing events.
UpdateOfferer	event	ListingInstalled	fixed	installationId + releaseId	Offers installation updates when a listing points to a newer release; applies them automatically only where the installing tenant's policy allows.

Actors and grains

None modelled

No grains are modelled for this item yet.

Sagas and long-running flows

None modelled

No sagas are modelled for this item yet.

stateDiagram-v2
    [*] --> Draft
    Draft --> InReview: Submit
    InReview --> Listed: Approved (publication class for Public)
    InReview --> Draft: ChangesRequested
    Listed --> Suspended: policy or evidence issue
    Suspended --> Listed: Resolved
    Listed --> Delisted: release Deprecated or Revoked, or publisher delists
    Delisted --> [*]

Hold "Alt" / "Option" to enable pan & zoom

sequenceDiagram
    participant WA as Workspace admin
    participant C as MarketplaceCatalogService
    participant L as LicenseService
    participant PE as PolicyEngineService
    participant AR as AgentRegistryService
    WA->>C: InstallListing (listing, project)
    C->>L: CheckEntitlement
    C->>PE: Decide (install listing kind in this tenant)
    C->>AR: create scoped release reference
    C-)WA: ListingInstalled

Hold "Alt" / "Option" to enable pan & zoom

Options and configuration

Section	Key	Type	Default	Reloadable	Secret	Summary
Marketplace:Catalog	PublicListingRequiresCertifiedPublisher	bool	true	no	no	Public visibility only for certified publishers.
Marketplace:Catalog	AutoUpdateDefault	bool	false	yes	no	Whether installations update automatically unless policy says otherwise.

Metrics and observability

Metric	Instrument	Unit	Dimensions	Summary
connectsoft.factory.marketplace.listings	updown	{listing}	kind, state, visibility	Listings by state.
connectsoft.factory.marketplace.installations	counter	{installation}	tenant, kind, state	Installations by outcome.
connectsoft.factory.marketplace.search_latency	histogram	ms	—	Search latency.

Security

Authentication	client-credentials
Scopes	factory.marketplace.read (Browse and search.); factory.marketplace.publish (Create and submit listings (certified publishers).); factory.marketplace.install (Install and remove in the caller's scope (Workspace admin, Asset maintainer).)
Roles	Requester, AssetMaintainer, WorkspaceAdmin, PlatformAdmin, Observer
Tenant isolation	row-filter
Data classification	internal
Max side-effect class	publication
Secrets	—

Dependencies

Outbound

Target	Kind	Purpose	Failure mode	Required
AgentRegistryService	grpc	Published releases, evidence; scoped references on installation.	fail-fast	yes
LicenseService	grpc	Entitlement checks and pricing references.	fail-fast	yes
PolicyEngineService	grpc	Tenant policy for installing a listing kind.	fail-fast	yes
ArtifactService	grpc	Listing documents.	degrade	no

Inbound

Target	Kind	Purpose	Failure mode	Required
AgentCardService	grpc	Listings for A2A discovery.	—	yes
StudioBff	sync-http	Marketplace views.	—	yes

Failure and recovery

Scenario	Detection	Recovery	Data impact	RTO (min)
Release revoked while installed	AssetReleaseRevoked	listing delisted; installations flagged and notified; runs keep pinned snapshots but new runs are refused by the registry	none	0

NFR targets

Target	Class value (pilot-interactive)	Override
latency_p95_ms	2000	—
availability_pct	99.5	—
throughput_rps	50	—
rpo_minutes	15	—
rto_minutes	240	—
cost_class	low	—

Deployment

Granularity	module of host · host MarketplaceHost
Topologies	saas-default
Runtime	—; replicas —–—
Ports	—

Current implementation

Nothing: the June-2026 pages described the nine asset types and an installation state machine; no catalog exists.

Later capabilities

Federated partner catalogs; curated collections per vertical (the examples section); semantic search over listing documents through the knowledge platform.

Decisions and traceability

Family	Ids
FR	FR-02, FR-04
FUX	FUX-01, FUX-03
NFR	NFR-13
XL	XL-03, XL-15

Related

• Overview · Workflows · LicenseService · AgentRegistryService · AgentCardService

• Marketplace microservices · bounded contexts · APIs · events · data model

• Services catalog · Ownership map