VEYNDO
Handbook
docs/app-package-installation-service.mdView source ↗

English source · 4 min

Install a private data App without Veyndo Core

Review a complete App package, explicitly approve it, configure its settings and use its declared records from your own application. HTTP, MCP and the existing JavaScript SDK call the same Rust operations. Native Veyndo shares the compiler, installation transaction and fixed-table model installer.

Enable installation explicitly

Provision the dedicated reader, managed writes and encrypted settings in that order. As their original migration owner, upgrade schema 3 to 4:

psql "$APP_DATA_MIGRATION_URL" -X -v reader_role=app_data_reader \
  -f data-service/sql/enable-installation.sql

Keep the serving connection on the existing restricted nonowner login. This upgrade adds two fixed tables, app_versions and app_storage_usage, and narrow package/model write grants. It preserves prior registered versions and initializes usage from actual existing records. It creates no table or index per App, shop or model. Schema tools and migration credentials never enter the serving image.

Add these values to the existing settings/write configuration:

Variable Value
APP_DATA_INSTALLS enabled
APP_DATA_INSTALL_SCOPES Operator-controlled JSON array, for example ["catalog.read","catalog.write"]

The scope catalogue names rights the existing identity owner actually understands. A package cannot register new rights or grant them to its caller. Every operation uses fresh fixed-endpoint introspection. Review and installation require apps.read apps.manage team.manage, a current merchant identity and actual personal_session: true, live: true claims from that owner. Delegated agents, machine keys and shopper identities cannot install. The ordinary reader, writer and settings profiles retain their previous schema and do not advertise install tools. Startup rejects profile mismatches, excessive grants, missing quota triggers or an owner/bypass serving login.

Review the complete package

Start with the complete example package. It declares its app_ namespace, version, private models, permissions, settings and bounded list/save action schemas. The complete native compiler checks the package before either operation. This profile supports portable private data Apps with scalar fields, list/save actions and declared installation settings. Native references, core extensions, indexes, public surfaces, commerce hooks, arbitrary code, schedules and schema migrations require their real host policies and are rejected here. Their native implementation stays with its existing owner.

POST /v1/packages/review
Authorization: Bearer <current personal resource access token>
Content-Type: application/json

{"manifest":{...complete package...}}

Review writes nothing. It returns the canonical digest, the package revision (zero for a new App), declared permissions, previous version and model/settings counts. It checks actual installed model compatibility and immutable version history. Compiler errors include their original message and field pointer where available. HTTP and MCP reject caller tenant, identity or environment properties.

Approve and install exactly what was reviewed

await client.initialize();
const review = await client.tool('apps.packages.review', {manifest});
const installed = await client.tool('apps.packages.install', {
  manifest,
  digest: review.digest,
  revision: review.revision,
  permissions: review.permissions,
  approve: true
});

HTTP uses POST /v1/packages/install with those same fields. The exact digest, current revision and complete permission list are mandatory. The package is compiled again at installation. Original install locks, the 128 Apps per shop limit, package CAS, model compatibility, immutable version, usage initialization and minimized app.installed event commit together. A late failure rolls the whole transaction back. Concurrent approval yields one winner; reload and review after a 409 conflict. After an uncertain network result, review current state before retrying.

Configure and use the installed App

The installed actions are immediately available through apps.records.read and apps.records.write with their current declared rights. The latter requires the installed digest, explicit approval and record revision. Declared secrets use the existing encrypted apps.settings.read / apps.settings.save workflow. Neither review nor a settings read returns secret values.

Run the executable SDK journey against a fresh test shop:

APP_DATA_URL=http://127.0.0.1:8799 \
APP_DATA_TOKEN='current-personal-resource-token' \
APP_DATA_SDK_MODULE=/absolute/path/sdk/src/index.js \
node data-service/examples/install.mjs

The example reviews, installs and writes/reads the new model through the unchanged generic SDK. MCP advertises the two management tools only when enabled. /v1/contract version 4 and /v1/openapi.json expose the same schemas.

Upgrade and storage behavior

Use a higher version for additive changes. Published version identities and their digests are immutable. Removing models/fields, changing field kinds or adding a required field without migration is rejected. Existing records retain their IDs, values and revisions. A changed installed package makes old settings noncurrent; review and configure the new version explicitly.

Forced signed RLS isolates shops. Database grants prevent package identity edits, version rewrites and direct usage-counter changes. Original limits of 100,000 records and 64 MiB per App apply to the same fixed record tables. Accounting and record model versions run inside the actual record transaction, so exceeding either budget leaves record, history and event unchanged. This service creates no OAuth issuer, second role store, second commerce ledger or SQL objects for individual Apps.

tests/acceptance.py exercises the actual Rust process, PostgreSQL, fixed identity endpoint, MCP and SDK, including two shops, revocation, approval errors, competing installs, additive upgrades, late rollback, immutable versions, quota boundaries and restart. Native Veyndo keeps its full resource-aware installation and sandbox publication path; this independent profile does not yet host jobs, restore, transport-secret rotation or native release orchestration.