Glossary
Plain-word definitions of every Ramose word, grouped A–Z. Guides link here on first use, and the row you were sent to is highlighted. In prose we use the plain word; the code uses the API name.
| Term | What it means | In the code |
|---|---|---|
| Alchemy | The TypeScript deploy tool Ramose uses: one file declares your Workers and storage; bun alchemy dev runs it on your laptop, bun alchemy deploy ships it. | Alchemy.Stack, alchemy dev / deploy |
| as of | Read the database exactly as it was right after version number t. Same query, one extra call. | db.asOf(t) |
| Better Auth | An open-source sign-in library. Reef uses it; the ramose/better-auth plugin mints Ramose tokens from it. | ramoseToken, ramoseTokenClient — Sign in and roles |
| capability | What your own Worker is allowed to do with Ramose: read-only or read-write databases. | ReadWriteDatabases, ReadDatabases — Use it from a Worker |
| client | The object that talks to the server for one page and hands out db handles. | Ramose.connect, Client, RamoseProvider |
| database | A named, isolated set of facts with its own writer. Naming one costs nothing; the first write creates it. | ramose.db(name, catalog) — One database per customer |
| database name | Letters, digits, . _ -, up to 64 characters, starting with a letter or digit. | Ramose.DATABASE_NAME_RE, Ramose.isDatabaseName |
| dbAfter | The same database pinned at the version your write produced — read your own write with no second round trip. | report.dbAfter — What a write returns |
| deny by default | An operation is refused unless a rule allows it. Forgetting a rule closes a door; it never opens one. | policy semantics — How rules combine |
| Durable Object | Cloudflare’s single-instance stateful Worker. Ramose runs the writer and the read copies as Durable Objects. | TransactorDO, QueryReplicaDO — What runs where |
| Effect | The TypeScript library Ramose is built on. Ramose calls return Effect values; the hooks run them; Effect.runPromise runs one elsewhere. | Effect.runPromise, yield* — Effect in five minutes |
| fact | One statement: this record’s field has this value, as of version t. Facts are added or removed, never overwritten. | datomCount (“how many facts landed”) |
| field (attribute) | One named, typed slot on a record type, e.g. issue.title. Its full name is :issue/title. | Ramose.Attr, Issue.title |
| Term | What it means | In the code |
|---|---|---|
| history | A read-only view that includes facts that were later removed. | db.history |
| id | Every record has a numeric id; every record type exposes it as a field for free. | Issue.id, Eid (an object { id }) |
| install | Write the schema into a database as an ordinary write. Safe to repeat. How Reef creates a workspace. | db.install(), Ramose.Database — Two doors to install the schema |
| issuer / audience | Who signed a token and who it is for; the server checks both. | RAMOSE_JWT_ISS, RAMOSE_JWT_AUD — The token the server verifies |
| JWKS | Your sign-in provider’s public keys, at a URL, used to verify tokens. | RAMOSE_JWKS_URL, RAMOSE_JWKS_JSON |
| live query | A query that re-runs itself whenever the database changes and hands your screen new rows. | db.live, useLive, livePull, usePull |
| local emulator | The Cloudflare runtime alchemy dev runs on your laptop; nothing leaves your machine. | — |
| lookup by unique key | Find a record by a unique field instead of its id: [User.sub, "abc"]. | LookupRef — Read one record |
| mint | Create and sign a token for a user, a database and a role. Done by your auth server, never by Ramose. | Ramose.claims, ramoseToken — Sign in and roles |
| Term | What it means | In the code |
|---|---|---|
| object storage | Cloudflare R2, where every version of every database is kept. | Cloudflare.R2.Bucket |
| one value or many | Whether a field holds one value or a set of values. Labels on an issue are “many”. | cardinality: "one" | "many" — Options |
| open mode | A server with no policy and no token: every caller is admin. Right for a laptop, wrong for the internet. | env unset — The three server modes |
| policy | The value that says which roles may read, create, change or remove which fields; compiled to JSON for the server. | Ramose.Policy, RAMOSE_POLICY |
| preset | A field the server fills from the caller on create (creator = you). A different client value is refused; the same value is a no-op. | P.preset(attr, P.principal) — Operations |
| pull | Read one record by id or unique key with a chosen set of fields; null if missing or a required field is absent. | db.pull, usePull, Ramose.Pull |
| query | A typed description of a read — record type, filters, order, fields — built as a value you can run once, live, or in the past. | Ramose.query, db.q, useQuery |
| query budget | A memory limit per query on the server; exceeding it fails the query with a 413 — narrow the query. | QueryBudgetExceeded, RAMOSE_QUERY_MAX_CELLS |
| read copy | Where queries run: a copy of the data near your users, kept current by the writer. | QueryReplicaDO |
| record (entity) | One thing in the database — an issue, a user — identified by an id: the set of facts about that id. | tx.entity(), retractEntity — The four verbs |
| record type (namespace) | A named group of fields, like a table: issue, user, label. | Ramose.Namespace("issue", {…}), policy ns: |
| reference | A field that points at another record — a typed foreign key. Queries can hop through it. | Ramose.Ref(() => User), .select, .reverse — Value types |
| remove / delete (retract) | Take a fact back: clear a field, or delete a whole record. History keeps it. | tx.retract, tx.retractEntity — The four verbs |
| role (class) | A role name carried in the sign-in token; rules refer to it. Reef: admin, member, viewer. admin bypasses every rule. | classes:, P.class(c), ramose.class — Expressions |
| row | One result of a query; its TypeScript type is inferred from the query. | Ramose.Row<typeof q> |
| schema (catalog) | Your data model as one TypeScript value: record types and their fields. Shared by app, rules and deploy. | Ramose.Catalog |
| the Ramose server (peer) | The Cloudflare Worker that serves all your databases. Its code ships with Ramose; you declare it, you don’t write it. | Cloudflare.Worker("Peer"), Ramose.Server, ramose/worker — The server |
| service binding | Cloudflare’s Worker-to-Worker call; how your Worker reaches the server without a URL. | Ramose.ServerBinding — Use it from a Worker |
| shape | The fields you ask a query or pull to return, including fields of referenced records. | .select({…}), .optional, .orDefault(v), Ramose.all(N) — Choose the fields |
| sign-in token (JWT) | A signed token the server verifies on every request and never issues; carries sub, the database name and the role. | Ramose.token.jwt / .static, TokenSource — What the token carries |
| signed-in user (principal) | The record that represents the caller, found by matching the token’s sub to a unique field. | principal: User.sub, P.principal, db.principal() |
| snapshot | A saved index of a whole database at a version. Retention counts snapshots. Reference only. | RAMOSE_RETAIN_ROOTS |
| stage | An Alchemy deployment environment (dev, prod). | --stage prod — Deploy |
| Term | What it means | In the code |
|---|---|---|
| tick / update | The server telling an open page that the version moved; live queries re-run. | useLive().ticks |
| time travel | Reading the database at an earlier version number with asOf. | db.asOf(t) — Time travel |
| token source | A self-refreshing credential: a function that fetches a token, re-minted near expiry. | Ramose.token.jwt(mint) — Tokens refresh themselves |
| unique key | A field whose value identifies one record; lets you look records up by it. | unique: "identity" — Options |
version number t (basis) | The number every write gets, in order. Reads happen at a version; asOf(t) picks one. Not a date. | report.t, db.basis(), useBasis |
| WebSocket connection (session) | The connection a browser holds to a database; carries reads and updates. Writes always use HTTPS. | GET /db/:name/session — HTTP API |
| Worker | Cloudflare’s serverless function. Your app’s backend and the Ramose server are Workers. | Cloudflare.Worker |
| workspace / customer (tenant) | One customer’s isolated data — one database. Reef’s word is workspace. | ramose.db(slug, Reef) — One database per customer |
| write (transaction) | A group of changes that lands completely or not at all; gets one version number; the only way data enters. | db.transact, TxReport |
| writer (transactor) | The one thing per database that commits writes, in order. | TransactorDO — The four promises |
Reference-only words
Section titled “Reference-only words”Words you will only meet in the Reference pages are defined where they appear: ident (a field’s full name, :issue/title), tempid, novelty, segment, indexer, group commit, TxReport / txEid / datomCount, ReadDb, authEnv / internalSecret, the RAMOSE_* settings, and the Effect words Layer, Stream, fiber and Scope (Effect in five minutes).
How we word these in the guides
The house style behind the table above: which word goes in the prose, and how an API name is introduced. Useful if you are writing for this site; skippable otherwise.
| Term | In prose |
|---|---|
| Alchemy | “Alchemy (the deploy tool)” |
| as of | “as it was at version t” |
| Better Auth | “Better Auth (the sign-in library)” |
| capability | “what the Worker may do” |
| client | “the client” |
| database | “database” |
| database name | “a valid name” |
| dbAfter | “the database right after your write” |
| deny by default | “deny by default” |
| Durable Object | “Durable Object (Cloudflare’s single-instance stateful Worker)” once, then “the writer” / “a read copy” |
| Effect | “Effect (the library Ramose is built on)” |
| fact | “fact” |
| field | “field” |
| history | “history” / “including what was deleted” |
| id | “record id” |
| install | “install the schema” |
| issuer / audience | “issuer / audience” |
| JWKS | “the sign-in provider’s public keys” |
| live query | “live query” |
| local emulator | “the local Cloudflare emulator” |
| lookup by unique key | “look up by unique key” |
| mint | “mint (issue) a token” |
| object storage | “object storage (R2)” |
| one value or many | “single-value / many-valued field” |
| open mode | “open” |
| policy | “permissions” (the topic) / “the policy” (the value) |
| preset | “server-filled field” |
| pull | “read one record” |
| query | “query” |
| query budget | “memory limit per query” |
| read copy | “read copy” |
| record | “record” |
| record type | “record type” / just “issues” |
| reference | “reference” |
| remove / delete | “clear a field” / “delete a record” |
| role | “role (a class in the policy)” |
| row | “row” |
| schema | “schema” |
| the Ramose server | “the Ramose server”, then “the server” |
| service binding | “service binding” |
| shape | “shape (the fields you ask for)” |
| sign-in token | “sign-in token”, then “token” |
| signed-in user | “the signed-in user” |
| snapshot | “snapshot” |
| stage | “stage” |
| tick / update | “update” |
| time travel | “time travel” |
| token source | “token source” |
| unique key | “unique key” |
version number t | “version number” / “version t”; “the version this view reads at” for basis |
| WebSocket connection | “the WebSocket connection” |
| Worker | “Worker” |
| workspace / customer | “workspace” (Reef) / “customer” |
| write | “write” |
| writer | “the writer” |