The Ramose mental model

Ramose is easier to learn if you begin with the whole model. Nearly every API is a consequence of the six ideas on this page.

1. One database is one graph

A Ramose database is a set of typed entities and relations governed by one deployed catalog and policy. Related data stays directly queryable instead of becoming a database-routing hierarchy.

2. The catalog is deployed code

A catalog packages a schema, policy, operations, traits, and documentation. It is immutable for one deployment. Deploying code changes the current catalog; application data does not install or select one.

The catalog definition is deployed code; application data cannot install or select a different one.

3. Reads are queries over an immutable value

A query is a typed, serializable description. In the app, the builder is bound to a database handle:

const open = projectDb.query.from(Task).where({ done: false })

Observed client queries run against a complete local authorized value and rerun when that value changes. The server never needs the UI’s live query. One-shot server and MCP queries run against the same logical query representation after authorization has filtered the database.

4. Writes are named operations

There is no public raw transaction endpoint. Every product change is an operation owned by an entity or trait. An operation has a stable name, input and output schemas, documentation, a server body, and optionally a pure optimistic projection.

The server alone checks the grant, resolves a visible target, executes the body, validates the change, and commits it. Offline clients queue intentions, not authority.

5. Offline state is a complete authorized replica

The browser persists the complete current authorized database. It does not persist query results. Queries derive answers from local indexes, so a new query can run offline without having been used before. One durable outbox survives restarts and coordinates across tabs.

6. Authorization shapes what exists for a caller

For a principal, Ramose constructs a filtered immutable database before evaluating reads. Hidden facts cannot affect joins, ordering, counts, relations, errors, or synchronization signals. Operation grants are separate and exact.

Web app query · mutate · offline

One deployed model Schema · policy · operations authorization is applied before either caller sees data

Agent describe · query · mutate

The application and MCP endpoint are two doors into the same model, not two backends that must be kept aligned.

That is why MCP is a thin surface. describe, query, and mutate discover and use the same visible catalog and operations as the web app. Adding an entity or operation changes capability data, not the MCP tool list.

Keep this picture in your head

deployment
  └─ authorized database
       ├─ local queries derive views
       ├─ named operations change state
       └─ app client and MCP share the same policy