VEYNDO
Handbook
extensions/services/app-storage/data-service/managed-writes.mdView source ↗

English source · 5 min

Managed App record writes and retained history

App Data service 0.2.0 adds an explicit optional write profile. Run portable private App records independently through HTTP, MCP and the existing Veyndo SDK. The same record mutation, state transition and bounded history implementation is embedded by native Veyndo. Default APP_DATA_MODE=read preserves schema 1 and its SELECT-only login. A read host never silently acquires write privileges.

Enable deliberately

Install the dedicated reader database first as described in the setup. Then, as its original migration owner, run:

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

This explicit upgrade requires schema 1 and the configured existing login. It adds two fixed tables, app_record_versions and outbox, then sets schema version 2. The four original application tables and the two fixed authority tables remain. No per-App/model/shop table or index is created.

Set APP_DATA_MODE=write and restart using that same restricted nonowner login and private scope key. Its new grants are limited to record INSERT/field-and-revision UPDATE, history SELECT/INSERT/retention DELETE, outbox INSERT and sequence USAGE. Package row locking needs UPDATE on the active column syntactically; the RLS policy has WITH CHECK false, so every actual package edit by this login is denied. It has no package installation, model/schema, record deletion or history update rights. Startup checks both the positive and forbidden grants. Serving code never runs migrations, accepts an owner connection or mints system database tickets.

This profile requires a separate operator-controlled upgrade. Switching the process back to read mode with the expanded writer grants fails startup. To return to a SELECT-only deployment, provision/revoke its profile through the operator's normal credential/schema workflow; there is no automatic downgrade or destructive cleanup.

Review and save

Read the private list action first. In the write profile, its response also contains packageDigest. This binds the reviewed request to the installed package. Then:

POST /v1/records/write
Authorization: Bearer <current App Data access token>
Content-Type: application/json

{"app":"cases","action":"save_case","packageDigest":"<reviewed 64 hex digest>","approve":true,"input":{"id":"case_1","revision":0,"fields":{"title":"New case","reference":"stable","status":"new"}}}

A new record uses revision 0; an update supplies the current revision. Explicit approve: true confirms the requested mutation, but grants no authority. The current identity must be a merchant with apps.read, apps.manage and the installed private save action's primary/additional scopes. Caller tenant/actor/ permissions/package definitions are not accepted. The installed input schema, exact typed fields and any declared output schema are checked.

One signed transaction locks the active package and record, checks the package digest and revision, validates App-owned states and immutable identity fields, captures retained history, writes the record and minimizes app.record.changed to App/entity/record/revision metadata. It validates the output before commit. An error rolls all these effects back. Concurrent updates to the same revision have one winner; the other receives revision_conflict. Repeated network writes are not automatically retried: inspect the current record/revision after an uncertain response.

Supported record policy

The initial portable write profile supports private declarative App-owned records with string, integer, boolean, JSON, exact decimal string, date and datetime fields, declared choices/validation and App-owned workflow states. Fields remain bounded by the actual shared model validator; request size is 128 KiB and stored fields are at most 64 KiB. The ordinary read profile retains its 16 KiB request bound.

Native object extensions, native references, assets/files, rich text, money, relations, translations, indexed/unique fields, public content, operational records and commerce configuration/hook/provider/lifecycle contracts require their actual host owners and are rejected with native_policy_required. This profile does not replace those validators with permissive defaults. It cannot edit the native site builder through its generic records path. The trusted installer must still admit the full package; this service exposes no install/seed shortcut.

History and agent use

POST /v1/records/history
Authorization: Bearer <current App Data access token>
Content-Type: application/json

{"app":"cases","action":"list_cases","id":"case_1"}

The current private list action's rights and the read scopes retained with each historical version must both hold. Only current declared fields are returned. Actor/source come from the authenticated host context. History is immutable and uses the original 20-version / 16 MiB App retention rules. No historical restore endpoint is claimed by this release.

MCP exposes apps.records.write and apps.records.history only in the enabled profile. The selected installed action additionally requires mcp: true; HTTP retains its own action admission. The same inputs work through the generic SDK:

const page = await client.tool('apps.records.read', {app:'cases', action:'list_cases', query:{}});
const saved = await client.tool('apps.records.write', {
  app:'cases', action:'save_case', packageDigest:page.packageDigest, approve:true,
  input:{id:'case_1', revision:0, fields:{title:'New case', reference:'stable', status:'new'}}
});
const history = await client.tool('apps.records.history', {app:'cases', action:'list_cases', id:saved.id});

The executable SDK example runs against the real service in acceptance. OpenAPI and /v1/contract describe the enabled profile. Identity is resolved freshly for every request; MCP opt-in never substitutes for current rights.

Acceptance boundary

The actual Rust service, fixed identity endpoint and real PostgreSQL test both profiles with two shops. Tests cover positive and forbidden role grants, package row locks without package edits, approval/digest/revision failures, CAS races, states/immutable fields, denied native policies, old history rights and retention, late event/history/output failures with full rollback, reconnect and SDK/MCP. The same suite runs against the nonroot Rust container on Linux.

This is managed portable record hosting. Complete independent package installation, settings, jobs, actual native resource policies, historical restore, sandbox publication and an autonomous outbox/Flow consumer remain separately tracked. Native Veyndo keeps all those existing host owners and uses the shared mutation and lifecycle/history hooks on its original transaction.