@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.
- package/dist/.source-hash +1 -1
- package/dist/index.js +4 -2
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
- package/skills/raybase-ai/SKILL.md +7 -0
- package/skills/raybase-auth/SKILL.md +29 -4
- package/skills/raybase-background-jobs/SKILL.md +54 -2
- package/skills/raybase-building/SKILL.md +23 -2
- package/skills/raybase-building/references/host-partitions.md +391 -0
- package/skills/raybase-building/references/interview-and-spec.md +12 -0
- package/skills/raybase-changing-a-live-app/SKILL.md +3 -1
- package/skills/raybase-data-and-policies/SKILL.md +84 -1
- package/skills/raybase-deploy/SKILL.md +18 -6
- package/skills/raybase-guide/SKILL.md +17 -0
- package/skills/raybase-mcp/SKILL.md +14 -0
- package/skills/raybase-notifications/SKILL.md +7 -0
- package/skills/raybase-pro-migration/SKILL.md +22 -0
- package/skills/raybase-schema/SKILL.md +40 -0
- package/skills/raybase-settings/SKILL.md +57 -3
- package/templates/astro-emdash/AGENTS.md +6 -5
- package/templates/astro-emdash/dev/SPEC.md +8 -0
- package/templates/react-router/AGENTS.md +6 -3
- package/templates/react-router/app/raybase.server.ts +5 -4
- package/templates/react-router/dev/SPEC.md +8 -0
- package/templates/tanstack-start/AGENTS.md +6 -5
- package/templates/tanstack-start/dev/SPEC.md +8 -0
|
@@ -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.
|
|
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
|
-
-
|
|
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
|
-
-
|
|
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
|
|
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
|
-
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
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 })
|
|
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.
|