Persistence and database strategy

Extensions must follow a layered persistence model.

11.1 Default rule

Do not introduce a custom extension-owned database unless host storage and thread/document APIs are insufficient.

11.2 Storage hierarchy

A. Ephemeral UI state

Use in-memory UI state only.

Examples:

• active tab
• filter toggles
• selection state

B. Small extension-owned persistent data

Use the host storage_* commands: native storage or the browser storage adapter. Both retain device-local semantics; neither is canonical dashboard project storage.

Commands:

• storage_put()
• storage_get()
• storage_delete()
• storage_list()

Rules:

• Native storage is isolated per extension ID; browser storage is isolated by dashboard origin, authenticated account and extension ID.
• use this for small configuration and lightweight persistent state

The browser host keeps bounded JSON values in its own account-scoped local storage, with a 4 MiB extension limit and explicit storage-denial/quota errors. It works independently of the chat worker lock. Reload preserves values; an account-local browser reset removes only that account's preferences, conversation database and extension drafts. It preserves other accounts and server project files. Extension frames do not receive direct access to the host's storage, session or credentials. Check the advertised storage commands before use.

C. Host-owned conversational/workspace state

Use thread commands when the data belongs to chat or workspace interaction state.

D. Dashboard-backed extension project state

Use the host filesystem bridge for canonical extension-owned data that must be shared through a dashboard. Follow Dashboard-backed extension project sync; device-local extension storage must not become a fallback source of truth for shared projects.

Browser dashboard file writes use online confirmation. A file's syncable metadata does not create a browser offline queue or turn device-local drafts into accepted shared data. Native offline/RIBLT behavior is a separate host capability. Browser upload/delete/atomic-write adapters remain subject to gateway enablement and the outstanding live storage/authorization tests described in the cloud write plan.

E. Searchable document memory

Use extension_upsert_document_snapshot() for retrieval-oriented text snapshots.

F. Custom native database

Only use a custom native DB when the extension has complex domain persistence requirements that cannot be reasonably expressed through host storage layers.

11.3 Custom database requirements

If an extension uses its own database, its documentation must define:

• why host persistence is insufficient
• engine choice
• file location
• schema versioning strategy
• migration strategy
• reset behavior
• uninstall behavior
• backup/export expectations
• scope rules for user, workspace, and entity ownership

Extension documentation must explicitly address schema drift and stale datastore risks.