@raybase/create 0.3.14 → 0.3.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -44,7 +44,11 @@ cover users, data, permissions, workflows, and the exact signup line as
44
44
  unapproved. The signup line must be exactly `Signup mode: invite-only`,
45
45
  `Signup mode: public self-signup`, or `Signup mode: provider-only self-signup`, and the Access section must also contain
46
46
  `Cloudflare email capability`, `Auth email features`, `Invite delivery`, and
47
- `Password recovery` lines. Ask the interview questions and stop before schema
47
+ `Password recovery` lines. It also records `Host partitions: none` or
48
+ `Host partitions: one customer's <plural> on <platform>`; when that line is
49
+ missing, settle the decision with
50
+ [references/host-partitions.md](references/host-partitions.md) and add it
51
+ rather than invalidating an otherwise approved spec. Ask the interview questions and stop before schema
48
52
  or screens in non-interactive contexts. If the spec's why or success criteria
49
53
  are unclear, ask a targeted follow-up before making product tradeoffs, but do
50
54
  not invalidate an otherwise approved spec solely because it lacks a dedicated
@@ -155,7 +159,24 @@ that matrix to keep app roles, policies, and screens aligned.
155
159
  parentheses), then implement validated domain routes/actions
156
160
  that enforce ownership, role gates, field allowlists, and allowed state
157
161
  transitions before using an audited service context for the write.
158
- - Multi-tenancy, one app installed by many customer organizations, and SSO across apps are provided by Raybase Pro. Core is single-tenant by design; converting it yourself means re-architecting the control plane and is not a supported path.
162
+ - Host partitions are for one customer's several accounts on a host
163
+ platform, such as one merchant's Shopify stores, one company's Slack
164
+ workspaces or Atlassian sites. They share one database, one set of
165
+ operators and any shared tables, and the host decides who is in which.
166
+ They are never for separate customers. If the app will serve unrelated
167
+ businesses, be listed publicly, let organizations sign themselves up, or
168
+ bill, brand or administer each customer separately, it needs Raybase Pro,
169
+ which gives each customer its own database, members and admins. If you
170
+ cannot tell whether the accounts belong to one customer, ask before
171
+ planning; do not turn partitions on by guess.
172
+ - Read [references/host-partitions.md](references/host-partitions.md)
173
+ before the first schema change whenever the app runs inside a host
174
+ platform or the spec says `Host partitions: one customer's ...`. It owns
175
+ the decision rule, the exact "Recommending Pro" wording, and the
176
+ partition developer surface (`appConfig.partitions`, partitioned and
177
+ shared tables, `ctx.partition`, lifecycle calls, doctor checks). Never
178
+ add tenant or customer scoping columns by hand; SSO across apps is also
179
+ Raybase Pro.
159
180
  - Keep `mcp: { enabled: true }` unless the human explicitly disables AI
160
181
  client access. If adding MCP tools, resources, or MCP Apps UI, read and
161
182
  follow the `raybase-mcp` skill before implementing that slice.
@@ -0,0 +1,391 @@
1
+ # Host Partitions
2
+
3
+ Read this before the first schema change when the app runs inside a host
4
+ platform that signs people in, or when `dev/SPEC.md` says `Host partitions:
5
+ one customer's ...`. It owns the choice between plain Core, host partitions,
6
+ and Raybase Pro, the wording for recommending Pro, and the partition developer
7
+ surface.
8
+
9
+ Host partitions are for one customer's several accounts on a host platform,
10
+ such as one merchant's Shopify stores, one company's Slack workspaces or
11
+ Atlassian sites. They share one database, one set of operators and any shared
12
+ tables, and the host decides who is in which. They are never for separate
13
+ customers. If the app will serve unrelated businesses, be listed publicly, let
14
+ organizations sign themselves up, or bill, brand or administer each customer
15
+ separately, it needs Raybase Pro, which gives each customer its own database,
16
+ members and admins. If you cannot tell whether the accounts belong to one
17
+ customer, ask before planning; do not turn partitions on by guess.
18
+
19
+ Raybase Core serves one customer. The line between Core and Pro is customers,
20
+ not host accounts. Doctor and the runtime check that partitions are declared
21
+ correctly; nothing checks whether they were the right choice. This file is
22
+ that check, so apply it every time.
23
+
24
+ ## Decide
25
+
26
+ **Partitions** when all three hold:
27
+
28
+ 1. the app runs inside a host platform that signs people in;
29
+ 2. every install belongs to one customer;
30
+ 3. those installs share staff, data or operators.
31
+
32
+ **Pro** when any one holds:
33
+
34
+ - unrelated customers ("merchants", "clients", "tenants", "sell it to");
35
+ - a public listing;
36
+ - self-serve sign-up of organizations or trials;
37
+ - per-customer billing, plans or seats;
38
+ - per-customer branding, white-label or custom domains;
39
+ - customer-managed admins or SSO;
40
+ - a contractual need for per-customer isolation.
41
+
42
+ **Plain Core:** one host account, or a business with locations and no host
43
+ platform. Several locations or brands on Raybase's own sign-in are a
44
+ `locations` table in plain Core, never partitions.
45
+
46
+ **Ambiguous cases:**
47
+
48
+ - Unsure whether the installs are one customer's: ask. If you can't ask,
49
+ print the question and stop; never default to partitions.
50
+ - One customer today, maybe public later: partitions, with "public listing →
51
+ Pro migration" recorded under SPEC risks.
52
+ - An agency serving several clients' stores: Pro.
53
+ - A franchise: Pro, unless the franchisor runs every store itself, so ask.
54
+ - A multi-vendor marketplace: Pro.
55
+ - Internal chargeback by store: fine on partitions.
56
+
57
+ Record the decision in the spec's Access section, in exactly one line:
58
+
59
+ ```md
60
+ Host partitions: none
61
+ ```
62
+
63
+ ```md
64
+ Host partitions: one customer's stores on Shopify
65
+ ```
66
+
67
+ The second form is `Host partitions: one customer's <plural> on <platform>`.
68
+ `raybase doctor` (`partition-spec`) warns when partitions are on and the line
69
+ is missing, and errors when the line and `appConfig.partitions` disagree.
70
+
71
+ ## Recommending Pro
72
+
73
+ Say this as soon as a Pro signal appears: before spec approval, and again when
74
+ a later change introduces one. Fill the brackets with what you heard and the
75
+ platform's own noun for an account.
76
+
77
+ > "This app would serve several separate customers ([what you heard]).
78
+ > Raybase Core keeps one customer's data together. It can keep one
79
+ > customer's own stores apart, but it is not built to keep different
80
+ > customers apart. Raybase Pro gives each customer its own database,
81
+ > people and admins. I recommend building this on Pro. Is that the way you
82
+ > want to go, or are these all one customer's [stores]?"
83
+
84
+ Then wait. Do not build a Core app with partitions, tenant columns, or a
85
+ customers table standing in for tenants to avoid the answer. For an existing
86
+ Core app, a Pro signal is a product change: stop and recommend Pro before
87
+ writing code (`raybase-pro-migration` covers the move).
88
+
89
+ ## Turn Partitions On
90
+
91
+ Partitions come only from a host platform's sign-in. They need `hostAuth`,
92
+ which an outside starter for that platform normally supplies; Raybase's own
93
+ sign-in, invites, and signup never put anyone in a partition.
94
+
95
+ ```ts
96
+ export const appConfig = {
97
+ appName: "Store Ops",
98
+ roles: appRoles,
99
+ auth: { signupMode: "invite-only", publicRoutes: [] },
100
+ partitions: {
101
+ label: { one: "Store", other: "Stores" }, // the word people see; default "Partition"
102
+ dev: ["dev-a", "dev-b"] // ensured when local development starts; this is the default
103
+ }
104
+ } satisfies RaybaseConfig;
105
+ ```
106
+
107
+ - `createRaybaseApp` refuses `appConfig.partitions` without `hostAuth`
108
+ (doctor: `partition-host-auth`), and refuses `hostAuth.authorizePartition`
109
+ without partitions.
110
+ - With partitions on, every table, bucket, job, and Agent schedule trigger
111
+ declares its partition; there is no default. With them off, declaring one is
112
+ an error (doctor: `partition-declaration`).
113
+ - Bind a `RAYBASE_BACKUPS` bucket with `raybase backups enable` (doctor:
114
+ `partition-backups`). A partition's erasure is recorded there, so a backup
115
+ restore or point-in-time recovery cannot bring it back.
116
+ - Raybase Pro refuses partitions for now (doctor there reports
117
+ `partitions-unsupported`).
118
+
119
+ ## Tables
120
+
121
+ ```ts
122
+ export const orders = raybaseTable("orders", {
123
+ id: id(),
124
+ number: text({ required: true, unique: true }), // unique per partition
125
+ productId: ref(() => products), // shared table: plain reference
126
+ createdAt: createdAt()
127
+ }, { partition: "partitioned", policies: { read: role(appRoles, "user"), create: denyAll, update: denyAll, delete: denyAll } });
128
+
129
+ export const products = raybaseTable("products", {
130
+ id: id(),
131
+ title: text({ required: true })
132
+ }, { partition: "shared", policies: { read: role(appRoles, "user"), create: operator(), update: operator(), delete: operator() } });
133
+ ```
134
+
135
+ - `partitioned`: rows belong to one host account. Core adds and owns a
136
+ `partitionKey` column. Never declare it (doctor: `partition-column`), and
137
+ never add your own tenant, store, or account key column instead (doctor's
138
+ `tenant-column` fails tenant and organization id columns and sends separate
139
+ customers to Pro).
140
+ - `shared`: one set of rows every partition sees through its policies, such
141
+ as a catalog or reference data. If the plain `user` role can write a shared
142
+ table, a host user in any partition can change what every partition sees
143
+ (doctor warns: `partition-shared-write`); keep shared writes on `operator()`
144
+ or a narrow role unless that is intended.
145
+ - `unique: true` on a partitioned table is unique per partition.
146
+ - A `ref()` from one partitioned table to another is a composite foreign key,
147
+ so no path, raw SQL included, can join rows across partitions.
148
+ - A shared table cannot reference a partitioned one (doctor:
149
+ `partition-shared-ref`): its rows would point into one partition while every
150
+ partition sees them.
151
+ - Partitions start from empty tables. Making a table that already holds rows
152
+ partitioned is refused at migration time; locally, reset the data (delete
153
+ `.wrangler/state`) and migrate again. A raw insert without a partition
154
+ fails.
155
+
156
+ ## Files, Realtime, Search And Retrieval
157
+
158
+ ```ts
159
+ export const storage = raybaseStorage({
160
+ receipts: raybaseBucket("receipts", { partition: "partitioned", policies, maxSizeBytes: 5_000_000 }),
161
+ brand: raybaseBucket("brand", { partition: "shared", policies: brandPolicies, maxSizeBytes: 5_000_000 })
162
+ });
163
+ ```
164
+
165
+ - A partitioned bucket's files belong to one partition; their R2 keys sit
166
+ under `p/<key>/`, so an erasure deletes them by prefix. An upload made
167
+ across all partitions (an operator, app-wide work) names its partition
168
+ (`partitionKey` in the storage client's create input, or the operator's
169
+ chosen partition).
170
+ - Realtime sockets keep the scope they opened with. A subscription to a
171
+ partitioned table from a socket with no partition is refused; replay and
172
+ presence rooms stay within the socket's partition.
173
+ - Search and retrieval filter by partition before their per-row re-check: a
174
+ partition sees its own documents and partition-free ones (shared tables,
175
+ corpora). A retrieval index on Vectorize with a partitioned source needs a
176
+ metadata index on `pk` before vectors are upserted (doctor:
177
+ `partition-retrieval-index`):
178
+ `npx wrangler vectorize create-metadata-index <index> --propertyName=pk --type=string`,
179
+ then reindex.
180
+
181
+ Policies need nothing new. The partition filter runs first and in addition to
182
+ the policy; `allowAll` and `adminOverride` do not get past it.
183
+
184
+ ## Host Sign-In
185
+
186
+ ```ts
187
+ const hostAuth = defineRaybaseHostAuth({
188
+ provider: "acme",
189
+ async resolve({ request, env }) {
190
+ const claims = await verifyHostToken(request, env); // the host's own check
191
+ if (!claims) return null;
192
+ return {
193
+ subject: `${claims.account}:${claims.userId}`,
194
+ name: claims.userName,
195
+ partition: { key: claims.account, name: claims.accountName }
196
+ };
197
+ },
198
+ // Optional; can only narrow. Use the host's own per-account staff permissions.
199
+ async authorizePartition({ env, request, principal, partition, purpose }) {
200
+ return true;
201
+ }
202
+ });
203
+ ```
204
+
205
+ - `resolve` returns `{ subject, name?, partition: { key, name? } }`. The
206
+ host's token proves who and where in one check. `subject` decides whether
207
+ one person is one host user across accounts or one per account.
208
+ - With partitions on it fails closed: no partition → 401 `partition_required`;
209
+ an unknown key → 401 `partition_not_installed`; a suspended one → 401
210
+ `partition_inactive`; a throwing resolve → 401.
211
+ - Resolve never creates a partition (except unseen keys in local
212
+ development). Install does, through `ensureRaybasePartition`. A changed
213
+ `name` renames the partition.
214
+ - A key is 1-200 printable characters with no whitespace or `/`, and not `.`
215
+ or `..`: it is one segment of the admin's partition routes
216
+ (`/api/admin/partitions/<key>/...`, encoded with `encodeURIComponent`), and
217
+ a path that encodes `/` is refused. Anything else is 400
218
+ `partition_invalid`.
219
+ - `authorizePartition` gets `purpose` `host-user`, `operator`, `mcp-grant`, or
220
+ `operator-all`. False → 403; a throw → 503, never a fallback to allow. It is
221
+ not called for queued work, which was authorized when queued.
222
+ - `operator-all` means one thing everywhere. Allowed: an operator's read with
223
+ no partition named is unfiltered across every partition, app and system
224
+ tables alike. Refused: that read is 403 `partition_denied` on every surface
225
+ (admin, Operator MCP, an operator's app-level conversation, asked again on
226
+ every turn and each time its socket token is issued), and the operator names a partition
227
+ (`?partition=`, `x-raybase-partition`, the admin picker, `partition` on
228
+ Operator MCP tools), checked with purpose `operator`. Raybase never asks the
229
+ host per key to build an allowed set.
230
+ - On the admin data route (`/api/data/:table?admin=1`, its CSV export and its
231
+ reference picker), a system table is narrowed by the partition manifest
232
+ when a partition is named. A system table with no partition (`global`, such
233
+ as `_auth_users`) needs `operator-all`: refused, it is 403 even with a
234
+ partition named. The reference picker reads app tables in the request's
235
+ partition scope, and users as `/api/admin/users` does (the host users seen
236
+ in the named partition). With a partition named, a write to a system table
237
+ must leave the row in that partition.
238
+ - A write into a partition always asks purpose `operator` for it, whatever the
239
+ read scope: an `all` scope's `authorizeWrite` covers app-table creates,
240
+ updates and deletes, `inPartition` writes, files, jobs that name a
241
+ partition, and an operator's app-level conversation. operator-all governs
242
+ reads only.
243
+
244
+ ## Lifecycle
245
+
246
+ The host layer calls these server-only functions from its install, uninstall,
247
+ and data-request webhooks. Each is audited as service `raybase-host-lifecycle`.
248
+
249
+ - Install: `ensureRaybasePartition(env, { key, name })`. Idempotent; also
250
+ reactivates a suspended or erased partition (an erased one comes back
251
+ empty), and refuses while an erasure is still draining.
252
+ - Uninstall: `suspendRaybasePartition(env, key, { reason })`. Sign-ins,
253
+ grants and queued runs stop (a queued job run ends `denied`, a queued Agent
254
+ run `skipped`, each audited and not retried; a notification delivery not
255
+ yet sent is `cancelled` with `partition_suspended`, also while the
256
+ partition is erasing or erased), and the partition's schedules
257
+ pause (a reinstall resumes them; ones the app paused itself stay paused);
258
+ data is kept.
259
+ - Redact (the platform's data-removal request):
260
+ `eraseRaybasePartition(env, key, { reason })`. The tombstone is written to
261
+ `RAYBASE_BACKUPS` first, then access stops and one drain pass runs. Later
262
+ passes follow on the jobs queue (partitions require it; doctor checks
263
+ `partition-jobs`), and the scheduled maintenance sweep picks up a stalled one
264
+ (keep the app's cron trigger; doctor checks `partition-maintenance`). Follow it with `raybasePartitionErasure(env, key)`.
265
+ Every row, file, conversation (with its archived chapters), job, grant,
266
+ index entry and host user seen only there (with their devices, notification
267
+ preferences and settings) is deleted; the partition's audit keeps only the
268
+ `partition.erase.requested` and `partition.erased` records. The tombstone
269
+ erases it again after a restore to before the erasure. An erasure that meets
270
+ a chapter archive purge past its retry cap ends `failed` with the reason
271
+ (audited, shown in the admin's partitions pane) and stops; erasing again
272
+ resumes it.
273
+ - Export: `exportRaybasePartition(env, key, { includeTranscripts })` streams
274
+ NDJSON to `RAYBASE_BACKUPS` (a file is a `file` line, then base64
275
+ `fileChunk` lines). The first pass runs in the call; a larger export
276
+ continues pass by pass on the jobs queue, and is marked `failed` once its
277
+ heartbeat stops for thirty minutes. Partitions require the jobs queue
278
+ (doctor `partition-jobs`). Every pass refuses a partition being erased, and
279
+ the erasure drain fails the partition's unfinished exports and aborts their
280
+ multipart uploads before deleting anything. `raybasePartitionExport(env, exportId)`
281
+ reads its status. Operators use the admin or `raybase partitions export <key>`.
282
+ - Read: `getRaybasePartition` and `listRaybasePartitions`. Core's registry is
283
+ the source, so fan-out never depends on the platform's API.
284
+
285
+ ## Who Sees What
286
+
287
+ - Host users: exactly the partition their host identity names on that
288
+ request, plus shared tables per policy. Today host sign-in reaches agent
289
+ routes and the App MCP connector only, not `/api/actions`, files or
290
+ realtime; a host's embedded UI reaches the app through its agents until
291
+ that lands.
292
+ - Operators: every partition for reads by default; one when they pick it
293
+ (`?partition=<key>` or the `x-raybase-partition` header; the admin's
294
+ partition picker sets it; Operator MCP app-data tools take `partition`).
295
+ A selector names a partition only with one non-empty value: empty, bare,
296
+ repeated, or the query and header naming different keys is 400
297
+ `partition_not_named`, never a read across every partition.
298
+ Creates in a partitioned table must name a partition, and rows never move
299
+ between partitions. The admin's pane named after `label.other` lists
300
+ partitions with their rows, export and erase; it never creates one.
301
+ - Native non-operator users (Raybase sign-in): shared tables only. There is no
302
+ Raybase path into a partition.
303
+ - Agents inherit the partition of whoever they act for.
304
+ - Server code in a partition acts only on that partition's conversations by
305
+ id: `ctx.agents.compose`, `ctx.agents.conversations.*`, `ctx.agents.rooms.*`,
306
+ and runs, wakes and follow-ups bound with `{ mode: "chat", conversationId }`.
307
+ A conversation in another partition, or in none, is 403
308
+ `partition_denied`; app-wide code (no partition, or operator-all) reaches
309
+ any. A `thread` binding's key is the partition's own (one key in two
310
+ partitions is two threads), and `ctx.agents.runs.recent` reads the
311
+ caller's partition's runs only.
312
+ - Host-account connector grants are bound to one partition (`raybase-mcp`).
313
+
314
+ ## In Actions And Jobs
315
+
316
+ - `ctx.partition` is `{ kind: "one", key }`, `{ kind: "all" }`, or null.
317
+ - `ctx.db` is already scoped. `ctx.db.inPartition(key)` narrows an
318
+ all-partitions client to one; it cannot widen or switch a one-partition
319
+ client.
320
+ - Platform webhooks name the partition explicitly:
321
+ `db.forService(name, { partition })`, `enqueueRaybaseJob(..., { partition })`,
322
+ and `notifications.send(..., { partition })`.
323
+ - Notifications: host users only receive their own partition's. A send in a
324
+ partition reaches its host users and the native operators the host allows
325
+ there (purpose `operator`; every operator with no host check), never a
326
+ native user with no operator role; a send with no partition reaches native
327
+ users only (a `role` expands to its native users; naming a host user is
328
+ refused).
329
+ - Jobs declare `partition: "inherit" | "each" | "app"`; Agent schedule
330
+ triggers `"each" | "app"` (`raybase-background-jobs`).
331
+ - Settings can be `scope: "partition"` (`raybase-settings`).
332
+ - User pickers: `listAppUsers(raybaseAuthExecutor(ctx.env), { partition: ctx.partition })`
333
+ and `getAppUserById(..., { partition })` return users seen in that
334
+ partition; pass `includeOperators` to add operators. Once the app has
335
+ partitions they throw without `partition` (`{ kind: "all" }` for everyone).
336
+ - Local development: the `partitions.dev` keys are installed when local
337
+ development starts. The seed's client works across all of them and
338
+ `ctx.partitions` lists them; create in one with `db.inPartition(key)`. A
339
+ dev persona with `host: { subject, partition }` signs in the way the host
340
+ platform would, into that dev partition:
341
+
342
+ ```ts
343
+ auth: {
344
+ devUsers: [
345
+ { email: "dana@example.com", name: "Dana", role: "owner" },
346
+ { email: "staff-a@example.com", name: "Store A staff", host: { subject: "dev/staff-a", partition: "dev-a" } }
347
+ ]
348
+ }
349
+ ```
350
+
351
+ ## Not Automatic
352
+
353
+ Core filters every data-client path. These it does not, so the app must:
354
+
355
+ - Raw SQL through `ctx.control`, `appData`, or executors is not
356
+ partition-filtered on reads. Foreign keys still stop cross-partition writes;
357
+ reads are yours. Prefer the data client.
358
+ - Partition data copied into shared tables, JSON columns, settings, or
359
+ prompts is visible wherever that copy is.
360
+ - Outbound effects (emails, webhooks, calls to the platform) must target the
361
+ right account.
362
+ - Erased data leaves backups by count, not age. Each new backup keeps the
363
+ newest `RAYBASE_BACKUPS_RETAIN` archives (30 by default) and deletes the
364
+ rest; nightly, admin and host backups all count. An erased partition's data
365
+ stays in the archives taken before its erasure until that many newer
366
+ backups exist: about a month of nightly backups by default, sooner with
367
+ host backups (`POST /__raybase/host/backup`), never while backups are
368
+ stopped. Point-in-time recovery keeps its own window. Restoring an archive,
369
+ or recovering to a point, from before an erasure re-applies its tombstone
370
+ as the restore finishes, so the partition is erased again. Set
371
+ `RAYBASE_BACKUPS_RETAIN` (and how often the host backs up) to match the
372
+ platform's data rules.
373
+
374
+ ## Left Out On Purpose
375
+
376
+ Partitions are not a tenancy product. None of these exist per partition:
377
+ billing, metering, licensing or seats; branding of Raybase surfaces, custom
378
+ domains, auth or SSO; admins, invites or delegation beyond the host's own
379
+ staff permissions; backups or restore; quotas or AI caps; self-serve create,
380
+ join, export or erase; Operator MCP for a partition's staff. When the app
381
+ needs any of them, recommend Pro with the wording above. Per-account theming
382
+ through `partition`-scoped settings is fine: that is app data.
383
+
384
+ ## Verify
385
+
386
+ - `raybase doctor` reports no `partition-*` errors, and the spec's `Host
387
+ partitions:` line matches `appConfig.partitions`.
388
+ - A test or local check shows a host user in one dev partition cannot read or
389
+ write another partition's rows through the UI, actions, and generated MCP
390
+ tools.
391
+ - Every shared table's write policy is deliberate.
@@ -29,6 +29,11 @@ not draft the spec until those supplied materials have been reviewed.
29
29
  - What does the app do?
30
30
  - What problem does it solve, why does that matter, and what would success look like?
31
31
  - Who uses it?
32
+ - When the app runs inside another platform that signs people in (a Shopify,
33
+ Slack, or Atlassian app, for example): "Which platform, and whose accounts
34
+ will install it: only yours, or other businesses'?" Decide plain Core, host
35
+ partitions, or Raybase Pro from the answer with
36
+ [host-partitions.md](host-partitions.md).
32
37
  - What data does it track?
33
38
  - Who can see, create, update, and delete each kind of data?
34
39
  - Should the app use invite-only signup, public provider-and-password signup,
@@ -49,6 +54,13 @@ not draft the spec until those supplied materials have been reviewed.
49
54
  Default to `Cloudflare email capability: free-compatible`, `Auth email
50
55
  features: none`, `Invite delivery: admin-shared links`, and `Password
51
56
  recovery: admin-assisted`.
57
+ - Include exactly one `Host partitions:` line in the same Access section:
58
+ `Host partitions: none`, or `Host partitions: one customer's <plural> on
59
+ <platform>` (for example `Host partitions: one customer's stores on
60
+ Shopify`) when [host-partitions.md](host-partitions.md) says partitions.
61
+ `raybase doctor` errors when the line disagrees with `appConfig.partitions`.
62
+ When the customer may list the app publicly later, record "public listing →
63
+ Pro migration" under the spec's risks.
52
64
  - Invite-only remains the default placeholder. Public self-signup is allowed
53
65
  only when explicitly approved, creates normal `user` users only, never
54
66
  creates Raybase operators/admins, and leaves Raybase `/admin`
@@ -103,7 +103,9 @@ Notes:
103
103
  - The Raybase Durable Object applies the new bundle lazily on first database access after deploy.
104
104
  - For a production backup, use `raybase backup --url <app-url> --cookie <admin-cookie>`; it downloads an envelope-encrypted whole-database `.rbb` archive from the deployed app.
105
105
  - Point-in-time restore rewinds app rows and Raybase users/sessions together. This is intentional whole-database consistency.
106
- - Multi-tenancy, one app installed by many customer organizations, and SSO across apps are provided by Raybase Pro. Core is single-tenant by design; converting it yourself means re-architecting the control plane and is not a supported path.
106
+ - Host partitions are for one customer's several accounts on a host platform, such as one merchant's Shopify stores, one company's Slack workspaces or Atlassian sites. They share one database, one set of operators and any shared tables, and the host decides who is in which. They are never for separate customers. If the app will serve unrelated businesses, be listed publicly, let organizations sign themselves up, or bill, brand or administer each customer separately, it needs Raybase Pro, which gives each customer its own database, members and admins. If you cannot tell whether the accounts belong to one customer, ask before planning; do not turn partitions on by guess.
107
+ - A change that introduces a Pro signal is a product change; stop and recommend Pro. Pro signals are unrelated customers, a public listing, self-serve sign-up of organizations or trials, per-customer billing, plans or seats, per-customer branding, white-label or custom domains, customer-managed admins or SSO, and a contractual need for per-customer isolation. Use the "Recommending Pro" wording in `.agents/skills/raybase-building/references/host-partitions.md`, and do not add tenant columns or turn partitions on to avoid the answer. SSO across apps is also Raybase Pro.
108
+ - Turning partitions on, or changing a table between `partitioned` and `shared`, is a schema change: follow `.agents/skills/raybase-building/references/host-partitions.md`, keep the spec's `Host partitions:` line aligned, and run `raybase doctor`.
107
109
  - Operator MCP is the operator-scoped production evidence and narrow typed
108
110
  admin-action endpoint at `/mcp/operator`; it should usually stay enabled
109
111
  alongside app MCP with `mcp: { enabled: true }`. Disable all MCP with
@@ -131,6 +131,10 @@ Rules:
131
131
  - Keep the spec's `Cloudflare email capability`, `Auth email features`,
132
132
  `Invite delivery`, and `Password recovery` lines aligned with
133
133
  `appConfig.auth.email`; run `raybase doctor` after auth email changes.
134
+ - Keep the spec's `Host partitions:` line aligned with `appConfig.partitions`:
135
+ `Host partitions: none` means no `partitions` key, and `Host partitions:
136
+ one customer's <plural> on <platform>` means partitions are on (see Host
137
+ Partitions below).
134
138
  - Destructive migrations require human approval, rollback or backup awareness,
135
139
  and verification of what data will be dropped before using
136
140
  `--allow-destructive`.
@@ -251,6 +255,25 @@ try {
251
255
  }
252
256
  ```
253
257
 
258
+ A write the database refuses because it breaks a unique (or primary-key),
259
+ foreign-key, not-null or check constraint throws `RaybaseConstraintError`. Its
260
+ message is SQLite's own (`UNIQUE constraint failed: passes_used.key: ...`);
261
+ `constraint` is `unique`, `foreign_key`, `not_null` or `check`, and `table` and
262
+ `columns` name what SQLite names (it never names them for a foreign key or a
263
+ check). A caught conflict is an ordinary outcome: it is not reported as an
264
+ uncaught exception anywhere.
265
+
266
+ ```ts
267
+ try {
268
+ await ctx.db.create("passes_used", { key });
269
+ } catch (error) {
270
+ if (error instanceof RaybaseConstraintError && error.constraint === "unique" && error.columns.includes("key")) {
271
+ return { alreadyUsed: true };
272
+ }
273
+ throw error;
274
+ }
275
+ ```
276
+
254
277
  When the surface is legitimately privileged server code that must read across
255
278
  user ownership, grant a named service principal on that table's `read` policy
256
279
  and use `.forService(name)` as shown below. Keep the name and table grant narrow;
@@ -374,4 +397,64 @@ Routes that authenticate through something other than a Raybase session
374
397
  reach app tables through an audited service context. A service context
375
398
  bypasses policies, so those routes must scope every read and write to the
376
399
  caller themselves. Policies are still mandatory on every table — they govern
377
- `/admin`, `/api/data`, and any future membership-mapped access.
400
+ `/admin`, `/api/data`, and any future membership-mapped access. In an app with
401
+ host partitions, such a route names the partition its caller proved:
402
+ `db.forService(name, { partition: key })`.
403
+
404
+ ## Host Partitions
405
+
406
+ Host partitions let one app serve one customer's several accounts on a host
407
+ platform (one merchant's stores, one company's workspaces) in one database.
408
+ They are never for separate customers: unrelated businesses, public listings,
409
+ self-serve organizations, or per-customer billing, branding, or admins need
410
+ Raybase Pro, which gives each customer its own database. The decision rule and
411
+ the wording for recommending Pro live in
412
+ `.agents/skills/raybase-building/references/host-partitions.md`; read it
413
+ before turning partitions on.
414
+
415
+ With `appConfig.partitions` set, every table declares one of two modes, and
416
+ none may when partitions are off (doctor: `partition-declaration`):
417
+
418
+ ```ts
419
+ export const orders = raybaseTable("orders", columns, {
420
+ partition: "partitioned",
421
+ policies: { read: role(appRoles, "user"), create: role(appRoles, "user"), update: owns("createdBy"), delete: denyAll }
422
+ });
423
+
424
+ export const catalog = raybaseTable("catalog", catalogColumns, {
425
+ partition: "shared",
426
+ policies: { read: role(appRoles, "user"), create: operator(), update: operator(), delete: operator() }
427
+ });
428
+ ```
429
+
430
+ - `partitioned` rows belong to one host account. Core adds and owns the
431
+ `partitionKey` column and filters every data-client path by it. Never
432
+ declare `partitionKey` (doctor: `partition-column`), and never hand-make a
433
+ tenant, store, account, or customer key column instead (doctor fails tenant
434
+ and organization id columns as `tenant-column`).
435
+ - `shared` rows are one set every partition sees, through the table's
436
+ policies. Host users of every partition hold the plain `user` role, so a
437
+ shared table that role can write lets any partition change what all of
438
+ them see; doctor warns (`partition-shared-write`). Keep shared writes on
439
+ `operator()` or a narrow role unless that is intended.
440
+ - `unique: true` columns on a partitioned table are unique per partition, not
441
+ across the app.
442
+ - A `ref()` between two partitioned tables becomes a composite foreign key on
443
+ `(partitionKey, id)`, so no path, raw SQL included, can join rows across
444
+ partitions. A partitioned table may reference a shared one. A shared table
445
+ cannot reference a partitioned one (doctor: `partition-shared-ref`).
446
+ - Policies need no partition term: the partition filter runs first, in
447
+ addition to the policy, and `allowAll` and `adminOverride` do not get past
448
+ it. Only an operator or app-wide (`all`) scope reads across partitions, and
449
+ creates there must name the partition (`ctx.db.inPartition(key)`).
450
+ - `userRef()` values in a partitioned row must name a user seen in that
451
+ partition, or an operator. Build pickers with
452
+ `listAppUsers(raybaseAuthExecutor(ctx.env), { partition: ctx.partition })` and verify with
453
+ `getAppUserById(raybaseAuthExecutor(ctx.env), id, { partition: ctx.partition })`; add
454
+ `includeOperators: true` when operators are valid choices.
455
+ - Raw SQL through `ctx.control`, `appData`, or executors is not
456
+ partition-filtered on reads. Prefer the data client; if raw SQL is
457
+ unavoidable, filter by `partitionKey` yourself.
458
+ - Copying partition data into a shared table, a JSON column, settings, or a
459
+ prompt makes it visible wherever the copy is. Keep partition data in
460
+ partitioned tables.
@@ -102,17 +102,29 @@ Notes:
102
102
 
103
103
  - `raybase deploy` builds the app before `wrangler deploy`.
104
104
  - Raybase stores auth state in Better Auth tables inside the Durable Object and
105
- uses `BETTER_AUTH_SECRET`; do not create or set `RAYBASE_AUTH_SECRET`.
105
+ uses `BETTER_AUTH_SECRET`.
106
106
  - External auth provider credentials belong in Worker secrets for deployment
107
107
  and local `.dev.vars` for development. Core external auth remains
108
108
  invite-only app login, not suite SSO; run `raybase doctor` after changing
109
109
  `src/raybase.auth.ts` or `auth.externalProviders`.
110
110
  - Point-in-time restore rewinds app rows and Raybase users/sessions together.
111
111
  This is intentional whole-database consistency.
112
- - Multi-tenancy, one app installed by many customer organizations, and SSO
113
- across apps are provided by Raybase Pro. Core is single-tenant by design;
114
- converting it yourself means re-architecting the control plane and is not a
115
- supported path.
112
+ - Host partitions are for one customer's several accounts on a host
113
+ platform, such as one merchant's Shopify stores, one company's Slack
114
+ workspaces or Atlassian sites. They share one database, one set of
115
+ operators and any shared tables, and the host decides who is in which.
116
+ They are never for separate customers. If the app will serve unrelated
117
+ businesses, be listed publicly, let organizations sign themselves up, or
118
+ bill, brand or administer each customer separately, it needs Raybase Pro,
119
+ which gives each customer its own database, members and admins. If you
120
+ cannot tell whether the accounts belong to one customer, ask before
121
+ planning; do not turn partitions on by guess. SSO across apps is also
122
+ Raybase Pro.
123
+ - An app with `appConfig.partitions` needs a `RAYBASE_BACKUPS` bucket
124
+ (`raybase backups enable`; doctor `partition-backups`). A partition's
125
+ erasure is recorded there and applied again after a backup restore or
126
+ point-in-time recovery, so the restore cannot bring the partition back.
127
+ Older backups still hold its data until they age out.
116
128
  - A Worker's requests to another service that is itself behind Cloudflare
117
129
  arrive from one address Cloudflare shares across every Worker of every
118
130
  customer, so an API that allowlists callers by IP address or ASN cannot
@@ -166,7 +178,7 @@ ctx)` in the worker entry, ahead of the framework, as the templates have it;
166
178
  `raybase doctor` warns (`host-routing`) when it is missing. Each failed job
167
179
  attempt, and each run that ends failed without one (lease expired, denied),
168
180
  logs `console.error("raybase.job.failed", { job, runId, attempt, maxAttempts,
169
- retry })`, never with the input, and with the error's message only under
181
+ retry, partitionKey })` (`partitionKey` null for app-level work), never with the input, and with the error's message only under
170
182
  `appConfig.jobs.logFailureMessages: true`. See the
171
183
  hosting guide (`docs/hosting.md` on the Raybase site) for the full contract.
172
184
 
@@ -74,6 +74,23 @@ them off). The widget sends the host's token through the `fetch` option it
74
74
  passes to the agent client. Do not remove either, and do not "fix" a 401 by
75
75
  making the app surface public.
76
76
 
77
+ Raybase Core only (Raybase Pro refuses partitions): a Core app that serves
78
+ one customer's several host accounts (one merchant's stores) sets
79
+ `appConfig.partitions`, and `resolve` then returns
80
+ `{ subject, name?, partition: { key, name? } }`: the same check that proves
81
+ who the person is proves which account they are in. Guide conversations,
82
+ memory, and the actions Guide calls then run in that partition only, and the
83
+ host user never sees another partition's rows. With partitions on, sign-in
84
+ fails closed with 401: `partition_required` when resolve names no partition,
85
+ `partition_not_installed` for a key the host layer never installed with
86
+ `ensureRaybasePartition`, `partition_inactive` after
87
+ `suspendRaybasePartition`, and plain 401 when resolve throws. Resolve never
88
+ creates a partition outside local development. An optional
89
+ `hostAuth.authorizePartition` can only narrow access (false is 403, a throw
90
+ 503). Partitions are never for separate customers; those need Raybase Pro.
91
+ In a Core app, `.agents/skills/raybase-building/references/host-partitions.md`
92
+ has the decision rule and the rest of the surface.
93
+
77
94
  Rules:
78
95
 
79
96
  - Keep Guide opt-in. Enabling Guide means model calls may consume Workers AI.