Xema Store

The Xema Store is the canonical distribution surface for biomes. It is not a marketplace in the colloquial sense — Store listings are first-class XVFS objects (xema://store/biome/<id>), every listing operation is a capability call, and submission, review, and approval are biome lifecycle transitions, not free-form CRUD.

The Store sits under /store/... in XVFS. The owning service is xema-store-api, which app-platform-api and biome-host-api consume through capabilities only — never through direct DB access.

The four Store capabilities

Capability	Purpose	Endpoints that enforce it
`store:biome.list@1`	Catalog list / detail / version read; review-log read; license listing	`GET /listings`, `GET /listings/:id`, `GET /listings/:id/versions`, `GET /listings/:id/versions/:version`, `GET /listings/:id/versions/:version/review-log`, `GET /installs`, `GET /licenses`
`store:biome.submit@1`	Create or update a listing; submit a version; comment on a submission	`POST /listings`, `PATCH /listings/:id`, `POST /listings/:id/versions`, `POST /listings/:id/versions/:version/comment`
`store:biome.approve@1`	Approve or reject a submitted version	`POST /listings/:id/versions/:version/approve`, `POST /listings/:id/versions/:version/reject`
`store:biome.archive@1`	Archive a listing or a version; revoke a license	`POST /listings/:id/archive`, `POST /listings/:id/versions/:version/archive`, `POST /licenses/:id/revoke`

Every version lives under its listing — there is no separate top-level submission route. A submission is POST /listings/:id/versions, and every reviewer action addresses that version at /listings/:id/versions/:version/....

Every privileged endpoint asks the Xema policy decision point for a verdict before the write, and fails closed if it cannot get one. The five refs are the only authorization surface — there is no implicit admin override.

Listing lifecycle

A Store listing is XemaObjectKind.Biome with a BiomeLifecycle stage and one or more published versions:

text

1listing (created)
2  ↓
3  versions[]
4    each version: store-submitted → store-approved → archived
5                                  ↘ rejected (terminal)

Submitting a version writes a StoreListingVersion row with lifecycle store-submitted. Approval flips it to store-approved; rejection is terminal and records a ReviewLog entry. Archive is a separate transition reachable from any non-rejected state.

Listings themselves can also be archived; archive of a listing implicitly hides all its versions from new installs but keeps existing installs functional (they reference the version through their lockfile).

Installing a Store biome

The Store is a catalogue: you browse it and publish to it. It has no install or uninstall endpoint. Installation goes through biome lifecycle: the host plans the install, you review the plan, and it applies exactly what was planned. The Store is a catalogue you browse and publish to; it does not install. Uninstalling goes through the same lifecycle (plan, confirm, apply); see the CLI page.

Submission and review

Submission writes the manifest + bundle + permission digest into a StoreListingVersion row in lifecycle store-submitted. While in that lifecycle the version runs only in the store-review execution environment — no production org data, no production credentials, no network beyond what the environment allows.

The reviewer surface (POST /listings/:id/versions/:version/approve | /reject | /comment) writes ReviewLog rows that are the audit trail for the decision. Comments are not free-form admin notes — every comment is structurally addressable via GET /listings/:id/versions/:version/review-log for the publisher to read and respond to.

The Store biome

The Store backend ships as the xema-store biome. It is a base-scope biome and opt-in: nothing in the minimal floor needs it to boot, run a session or run a workflow, and a session's lockfile resolution treats it as optional enrichment. It owns the store capability domain and keeps the catalog: biome listings, submitted versions, install records and the review-log audit trail. The biome is itself listed in the Store.

Pricing

The data model carries a pricingPolicy field on StoreListing. Pricing is deferred and not active in this phase. The column exists so future activation does not require a schema migration; today every install behaves as if the policy is "free". When activation lands, Xema will handle billing transparently — biome authors and installers do not configure billing endpoints directly.

Cross-references with biome lifecycle

The Store does not own the biome lifecycle — biome-host-api does. The Store consumes biome.lifecycle transitions through capability calls. Approval of a submitted version is also the biome:approve-in-store@1 transition; installation is not a Store operation; it goes through biome lifecycle (plan, review, apply). Treat the Store and the biome host as two services agreeing on one lifecycle through capabilities.

store — concept summary
biome, lifecycle — the state machine the Store mediates
capability — every Store action resolves to one
execution-environment — store-review is where submissions run
lockfile, versioning — what installs pin
SDK / Publishing — the publisher-side flow

Previous: ← Canopy Next: Editions →