@rebasepro/types 0.16.0 → 0.16.1-canary.g041c925

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.
Files changed (53) hide show
  1. package/dist/call_context.d.ts +5 -5
  2. package/dist/controllers/auth_state.d.ts +1 -1
  3. package/dist/controllers/client.d.ts +22 -9
  4. package/dist/controllers/collection_registry.d.ts +2 -2
  5. package/dist/controllers/data.d.ts +4 -12
  6. package/dist/controllers/data_driver.d.ts +7 -7
  7. package/dist/controllers/email.d.ts +54 -2
  8. package/dist/controllers/index.d.ts +8 -9
  9. package/dist/controllers/storage.d.ts +4 -4
  10. package/dist/index.d.ts +5 -5
  11. package/dist/index.es.js +429 -3
  12. package/dist/index.es.js.map +1 -1
  13. package/dist/types/admin_block.d.ts +1 -1
  14. package/dist/types/auth_adapter.d.ts +18 -9
  15. package/dist/types/backend.d.ts +23 -10
  16. package/dist/types/collection_contract.d.ts +1 -1
  17. package/dist/types/collections.d.ts +16 -9
  18. package/dist/types/component_ref.d.ts +3 -2
  19. package/dist/types/cron.d.ts +1 -25
  20. package/dist/types/data_source.d.ts +1 -1
  21. package/dist/types/database_adapter.d.ts +5 -5
  22. package/dist/types/entities.d.ts +1 -1
  23. package/dist/types/entity_callbacks.d.ts +4 -4
  24. package/dist/types/index.d.ts +32 -29
  25. package/dist/types/project_manifest.d.ts +132 -27
  26. package/dist/types/properties.d.ts +58 -6
  27. package/dist/types/relations.d.ts +1 -1
  28. package/dist/types/resource_kinds.d.ts +174 -0
  29. package/dist/types/resources.d.ts +197 -0
  30. package/dist/types/schema_editing.d.ts +127 -0
  31. package/dist/types/schema_version.d.ts +1 -1
  32. package/dist/types/security_rules.d.ts +1 -1
  33. package/dist/users/index.d.ts +1 -1
  34. package/package.json +2 -2
  35. package/src/controllers/client.ts +14 -1
  36. package/src/controllers/data.ts +0 -9
  37. package/src/controllers/email.ts +55 -2
  38. package/src/controllers/index.ts +0 -1
  39. package/src/controllers/storage.ts +4 -4
  40. package/src/types/admin_block.ts +1 -2
  41. package/src/types/auth_adapter.ts +18 -10
  42. package/src/types/backend.ts +18 -1
  43. package/src/types/collections.ts +9 -2
  44. package/src/types/component_ref.ts +3 -2
  45. package/src/types/cron.ts +0 -24
  46. package/src/types/index.ts +3 -0
  47. package/src/types/project_manifest.ts +139 -26
  48. package/src/types/properties.ts +54 -0
  49. package/src/types/resource_kinds.ts +309 -0
  50. package/src/types/resources.ts +368 -0
  51. package/src/types/schema_editing.ts +154 -0
  52. package/dist/controllers/database_admin.d.ts +0 -11
  53. package/src/controllers/database_admin.ts +0 -22
@@ -20,6 +20,51 @@ export interface EmailSendOptions {
20
20
  text?: string;
21
21
  /** Optional reply-to address. */
22
22
  replyTo?: string;
23
+ /**
24
+ * Additional headers, verbatim.
25
+ *
26
+ * The reason this exists is that several things a real sender must do are
27
+ * only expressible as headers, and without a passthrough an application had
28
+ * to choose between not doing them and not using this interface:
29
+ *
30
+ * - `List-Unsubscribe` and `List-Unsubscribe-Post`, which give a mail client
31
+ * its own one-click opt-out. The large providers weigh their presence when
32
+ * deciding whether bulk mail reaches an inbox at all.
33
+ * - `In-Reply-To` and `References`, without which a reply is a new thread.
34
+ *
35
+ * **Values are validated, not escaped.** A value containing CR or LF is
36
+ * rejected rather than sanitised, because a newline in a header value ends
37
+ * the header and starts a new one — so a field built from user input is an
38
+ * injection point for `Bcc:` and anything else. Rejecting is the only safe
39
+ * response: silently stripping the newline would deliver a message the
40
+ * caller did not write, and neither would tell them.
41
+ */
42
+ headers?: Record<string, string>;
43
+ }
44
+
45
+ /**
46
+ * What the provider reported about a message it accepted.
47
+ *
48
+ * Every field is optional because not every backend reports them: a custom
49
+ * `sendEmail` function that posts to an HTTP API may know nothing beyond "no
50
+ * error". An absent `messageId` therefore means "not reported", never "not
51
+ * sent" — the absence of an id is not a delivery failure, which is signalled by
52
+ * a thrown error.
53
+ */
54
+ export interface EmailSendResult {
55
+ /**
56
+ * The message's RFC 5322 Message-ID, **without** angle brackets.
57
+ *
58
+ * Stripped because this is an identifier to store and compare — against a
59
+ * reply's `In-Reply-To`, most often — and a value that sometimes carries
60
+ * brackets and sometimes does not is a bug waiting in every comparison.
61
+ * Re-add them when writing it into a header: `<${messageId}>`.
62
+ */
63
+ messageId?: string;
64
+ /** Recipients the provider accepted, when it says. */
65
+ accepted?: string[];
66
+ /** Recipients the provider refused, when it says. A non-empty list is not an error. */
67
+ rejected?: string[];
23
68
  }
24
69
 
25
70
  /**
@@ -29,8 +74,16 @@ export interface EmailSendOptions {
29
74
  * provider — consumers only interact through this interface.
30
75
  */
31
76
  export interface EmailService {
32
- /** Send a single email. */
33
- send(options: EmailSendOptions): Promise<void>;
77
+ /**
78
+ * Send a single email.
79
+ *
80
+ * Resolves with what the provider reported (see {@link EmailSendResult});
81
+ * throws on failure. It returned `void` before 0.17: an application that
82
+ * sent a message had no way to learn the id the server assigned it, so
83
+ * threading a reply back to the message that prompted it was impossible
84
+ * through this interface. Callers that do not care may still ignore it.
85
+ */
86
+ send(options: EmailSendOptions): Promise<EmailSendResult>;
34
87
  /** Returns `true` when the service has valid credentials / is ready to send. */
35
88
  isConfigured(): boolean;
36
89
  /** Verify connection/credentials with the email provider. */
@@ -2,7 +2,6 @@ export * from "./collection_registry";
2
2
  export * from "./auth_state";
3
3
 
4
4
  export * from "./data";
5
- export * from "./database_admin";
6
5
  export * from "./data_driver";
7
6
 
8
7
  export * from "./effective_role";
@@ -68,11 +68,11 @@ export interface UploadFileResult {
68
68
  /**
69
69
  * Fully qualified storage URL for the uploaded file.
70
70
  *
71
- * For example: `s3://my-bucket/path/to/file.png`.
72
- *
73
- * This is optional for backwards compatibility.
71
+ * For example: `s3://my-bucket/path/to/file.png`. Every controller in the
72
+ * framework returns one — S3, GCS and local alike — and a caller that stores
73
+ * the reference needs it, so it is part of the result rather than a maybe.
74
74
  */
75
- storageUrl?: string;
75
+ storageUrl: string;
76
76
  }
77
77
 
78
78
  /**
@@ -71,8 +71,7 @@ export const ADMIN_COLLECTION_KEYS = [
71
71
  "selectionController",
72
72
  "selectionEnabled",
73
73
  "sideDialogWidth",
74
- "sort",
75
- "titleProperty"
74
+ "sort"
76
75
  ] as const;
77
76
 
78
77
  /** A key of a collection's `admin` block. @group Models */
@@ -83,8 +83,16 @@ export interface AuthAdapterCapabilities {
83
83
 
84
84
  /** Supports email/password login. */
85
85
  emailPasswordLogin: boolean;
86
- /** Supports new user registration. */
87
- registration: boolean;
86
+ /**
87
+ * Whether self-registration is open **right now**.
88
+ *
89
+ * A runtime answer, not a static feature list: the built-in adapter also
90
+ * reports `true` during the first-user bootstrap window (an empty user
91
+ * table) and `false` the moment `disableSelfRegistration` is set. Whatever
92
+ * this says, `POST /auth/register` does — both read the same predicate, so
93
+ * the UI can never be sent to a form that can only 403.
94
+ */
95
+ registrationEnabled: boolean;
88
96
  /**
89
97
  * Supports the end-user password reset flow (emailing a reset link).
90
98
  *
@@ -113,12 +121,15 @@ export interface AuthAdapterCapabilities {
113
121
  /** Supports passwordless magic link login. */
114
122
  magicLink: boolean;
115
123
  /**
116
- * Whether `POST /auth/anonymous` will mint a credential-less session.
124
+ * Supports passwordless sign-in with a six-digit code sent by email.
117
125
  *
118
- * Optional so an external adapter that predates the key keeps typechecking;
119
- * absent means "this adapter does not offer anonymous sign-in".
126
+ * Optional so that an external adapter written before this existed still
127
+ * satisfies the interface; absent reads as "no", which is what an adapter
128
+ * that has never heard of the flow means.
120
129
  */
121
- anonymousLogin?: boolean;
130
+ emailOtp?: boolean;
131
+ /** Whether `POST /auth/anonymous` will mint a credential-less session. */
132
+ anonymousLogin: boolean;
122
133
  /** List of enabled OAuth provider IDs (e.g. `["google", "github"]`). */
123
134
  enabledProviders: string[];
124
135
 
@@ -134,9 +145,6 @@ export interface AuthAdapterCapabilities {
134
145
  * Only applicable for built-in auth.
135
146
  */
136
147
  needsSetup?: boolean;
137
-
138
- /** Whether new user registration is enabled (may differ from `registration` capability at runtime). */
139
- registrationEnabled?: boolean;
140
148
  }
141
149
 
142
150
  // ─── User Management ────────────────────────────────────────────────────────
@@ -311,7 +319,7 @@ export interface TransformAuthResponseContext {
311
319
  /** The authenticated user's ID. */
312
320
  uid: string;
313
321
  /** The auth method that triggered this response. */
314
- method: "login" | "register" | "oauth" | "refresh" | "anonymous" | "magic-link" | "mfa";
322
+ method: "login" | "register" | "oauth" | "refresh" | "anonymous" | "magic-link" | "otp" | "mfa";
315
323
  /** The raw HTTP request (for reading headers, IP, etc.). */
316
324
  request: Request;
317
325
  }
@@ -4,6 +4,7 @@ import type { LogicalCondition } from "../controllers/data";
4
4
  import type { AuthAdapter } from "./auth_adapter";
5
5
  import type { HistoryConfig } from "../controllers/client";
6
6
  import type { ChannelBusSetting } from "./channel_bus";
7
+ import type { SchemaEditingAdmin } from "./schema_editing";
7
8
 
8
9
  // =============================================================================
9
10
  // DATABASE CONNECTION INTERFACES
@@ -564,7 +565,23 @@ export interface BranchAdmin {
564
565
  *
565
566
  * @group Admin
566
567
  */
567
- export type DatabaseAdmin = Partial<SQLAdmin> & Partial<DocumentAdmin> & Partial<SchemaAdmin> & Partial<BranchAdmin>;
568
+ export type DatabaseAdmin = Partial<SQLAdmin> & Partial<DocumentAdmin> & Partial<SchemaAdmin>
569
+ & Partial<BranchAdmin> & Partial<SchemaEditingAdmin>;
570
+
571
+ /**
572
+ * Type guard: can this admin plan a live schema change?
573
+ *
574
+ * Planning is engine-specific — it renders DDL, a Drizzle schema and the
575
+ * declarative SQL artifacts — so the implementation lives in the driver
576
+ * package. The server detects the capability structurally, exactly as it does
577
+ * for SQL, rather than importing an engine it is supposed to know nothing
578
+ * about.
579
+ *
580
+ * @group Admin
581
+ */
582
+ export function isSchemaEditingAdmin(admin: DatabaseAdmin | undefined): admin is SchemaEditingAdmin {
583
+ return !!admin && typeof (admin as SchemaEditingAdmin).planSchemaChange === "function";
584
+ }
568
585
 
569
586
  /**
570
587
  * Type guard: does this admin support SQL operations?
@@ -3,6 +3,7 @@ import type { CollectionCallbacks } from "./entity_callbacks";
3
3
  import type { EnumValues, Properties, PostgresProperties, FirebaseProperties, MongoProperties } from "./properties";
4
4
 
5
5
  import type { User } from "../users";
6
+ import type { EmailSendResult } from "../controllers/email";
6
7
  import type { Relation } from "./relations";
7
8
  import type { SecurityRule } from "./security_rules";
8
9
  import { getDataSourceCapabilities } from "./data_source";
@@ -702,8 +703,14 @@ export interface AuthCollectionConfig {
702
703
  export interface AuthCollectionContext {
703
704
  /** Hash a password using the configured algorithm (scrypt by default). */
704
705
  hashPassword: (password: string) => Promise<string>;
705
- /** Send an email. Only available when email service is configured. */
706
- sendEmail?: (options: { to: string; subject: string; html: string; text?: string }) => Promise<void>;
706
+ /**
707
+ * Send an email. Only available when email service is configured.
708
+ *
709
+ * Resolves with what the provider reported — the assigned Message-ID, most
710
+ * usefully — so a hook that sends a message can store the id and later
711
+ * thread a reply back to it. Callers that do not care may ignore it.
712
+ */
713
+ sendEmail?: (options: { to: string; subject: string; html: string; text?: string }) => Promise<EmailSendResult>;
707
714
  /** Whether the email service is configured and available. */
708
715
  emailConfigured: boolean;
709
716
  /** The app name from email config (for templates). */
@@ -2,8 +2,9 @@
2
2
  * How a collection points at a UI component without the backend learning about React.
3
3
  *
4
4
  * This file is the hinge the BaaS/admin split turns on. `ComponentRef` is named
5
- * by `properties.ts` (`ui.Field`, `ui.Preview`, `ui.Filter`), and `properties.ts`
6
- * must stay in the React-free core because every backend subsystem — validation,
5
+ * by a property's `admin` block (`admin.Field`, `admin.Preview`, `admin.Filter`)
6
+ * and imported by `properties.ts`, which must stay in the React-free core
7
+ * because every backend subsystem — validation,
7
8
  * the drizzle schema generator, the OpenAPI generator, the SDK codegen — reads
8
9
  * property definitions. If `ComponentRef` needed `React.ComponentType`, the whole
9
10
  * property model would have to move to the admin layer with it.
package/src/types/cron.ts CHANGED
@@ -1,5 +1,4 @@
1
1
  import type { RebaseServerClient } from "../controllers/client";
2
- import type { RebaseSdkData } from "../controllers/data";
3
2
 
4
3
  /**
5
4
  * Cron Job type definitions for Rebase.
@@ -126,29 +125,6 @@ export interface CronJobContext {
126
125
  */
127
126
  rebase: RebaseServerClient;
128
127
 
129
- /**
130
- * The same object as {@link rebase}, under the name this context used
131
- * before.
132
- *
133
- * @deprecated Use `rebase` instead. Two things made the old name a problem,
134
- * and neither was cosmetic. It contradicted every other server surface,
135
- * where the singleton is `rebase` — the previous docstring had to end with
136
- * *"it is only named `client` here"*. And typing it as `RebaseClient`
137
- * re-exposed `client.data`, the alias that {@link RebaseServerClient}
138
- * deliberately `Omit`s so the RLS-bypassing plane has exactly one name and
139
- * the privilege is visible at the call site. A reader who learned
140
- * `client.data` here carried it to a collection callback, where
141
- * `context.data` is the *user-scoped* plane — same spelling, opposite
142
- * privilege.
143
- *
144
- * Still the full server client at runtime, and `data` still resolves, so
145
- * existing cron files keep working and keep compiling. It will be removed
146
- * in the next major.
147
- */
148
- client: RebaseServerClient & {
149
- /** @deprecated Use `rebase.dataAsAdmin` — the name states the privilege. */
150
- data: RebaseSdkData;
151
- };
152
128
  }
153
129
 
154
130
  // =============================================================================
@@ -14,8 +14,11 @@ export * from "./security_rules";
14
14
  export * from "./entity_callbacks";
15
15
  export * from "./websockets";
16
16
  export * from "./backend";
17
+ export * from "./schema_editing";
17
18
  export * from "./channel_bus";
18
19
  export * from "./data_source";
20
+ export * from "./resources";
21
+ export * from "./resource_kinds";
19
22
  export * from "./storage_source";
20
23
  export * from "./cron";
21
24
  export * from "./backup";
@@ -26,6 +26,7 @@
26
26
  */
27
27
 
28
28
  import type { StorageSourceDefinition } from "./storage_source";
29
+ import type { ResourceGraph } from "./resources";
29
30
 
30
31
  /**
31
32
  * Which kind of thing an app is.
@@ -61,7 +62,7 @@ export interface RebaseBackendAppConfig {
61
62
  *
62
63
  * Independent of *where* it runs. Both run on Rebase Cloud and both
63
64
  * self-host — the destination lives in `.rebase/cloud.json`, not here. See
64
- * `docker/docker-compose.selfhost.yml`, which boots a managed bundle on a
65
+ * `infra/docker/docker-compose.selfhost.yml`, which boots a managed bundle on a
65
66
  * developer's own Docker host.
66
67
  *
67
68
  * This is authored rather than inferred on purpose. It is the single most
@@ -132,6 +133,38 @@ export interface RebaseStaticAppConfig {
132
133
 
133
134
  export type RebaseAppConfig = RebaseBackendAppConfig | RebaseStaticAppConfig;
134
135
 
136
+ /**
137
+ * Path prefixes the backend owns, which no static app may claim.
138
+ *
139
+ * One process — and, on the platform, one hostname — serves both the API and
140
+ * however many static apps a project has. Mounting is longest-path-first, so an
141
+ * app declaring `/api` would win against the API itself and every request to it
142
+ * would be answered with that app's `index.html`: a 200 carrying HTML where the
143
+ * caller expected JSON, from a project that looks deployed and healthy.
144
+ *
145
+ * Declared here rather than in either enforcer because both must agree. The CLI
146
+ * checks it so a developer finds out while editing `rebase.json`; the control
147
+ * plane checks it again at deploy intake, because the front door's correctness
148
+ * cannot rest on a check that ran in somebody else's CLI — and a repository can
149
+ * be deployed by a CLI older than this rule.
150
+ */
151
+ export const RESERVED_BACKEND_PREFIXES = ["/api", "/health", "/healthz", "/livez", "/readyz", "/metrics"] as const;
152
+
153
+ /**
154
+ * Whether `path` collides with a prefix the backend owns.
155
+ *
156
+ * Compares at segment boundaries, so `/api` and `/api/v2` collide while
157
+ * `/apidocs` does not — the same rule the router matches with, because a check
158
+ * that is stricter than the router rejects paths that would have worked, and one
159
+ * that is looser admits paths that will not.
160
+ */
161
+ export function reservedPrefixFor(path: string): string | undefined {
162
+ const normalized = path.endsWith("/") && path !== "/" ? path.slice(0, -1) : path;
163
+ return RESERVED_BACKEND_PREFIXES.find(
164
+ reserved => normalized === reserved || normalized.startsWith(`${reserved}/`)
165
+ );
166
+ }
167
+
135
168
  /**
136
169
  * One declared storage source, as authored in `rebase.json`.
137
170
  *
@@ -179,27 +212,20 @@ export interface RebaseProjectManifest {
179
212
  */
180
213
  apps: Record<string, RebaseAppConfig>;
181
214
  /**
182
- * Storage sources this project uses, keyed by source key.
215
+ * Buckets are NOT declared here any more.
183
216
  *
184
- * **Topology only — never credentials.** Which buckets exist is a property of
185
- * the project and belongs in the repository; how to reach each one is a
186
- * property of the deployment and lives in the environment, read per source
187
- * from `<BASE>__<KEY>` (`S3_BUCKET__MEDIA` for a source keyed `media`). The
188
- * default source takes no suffix, so a single-bucket project configured with
189
- * plain `S3_BUCKET` keeps working having declared nothing at all.
217
+ * They were, and the runtime merged this block with the declarations in
218
+ * config code — a bucket named in both had one engine kept and the other
219
+ * silently discarded. Two homes for one concept, with a merge to decide
220
+ * between them, is the shape this whole model replaced.
190
221
  *
191
- * Declared here rather than only in the config package because this file is
192
- * the one artifact a host can read *before* running a build. That is what
193
- * lets a console show "this project wants a `media` bucket, and it has none"
194
- * on a project's first deploy, and it is why the managed and custom runtimes
195
- * can present the same list — a custom build emits no bundle manifest, so a
196
- * declaration that lived only in compiled config would leave every custom
197
- * project invisible.
198
- *
199
- * Omitted entirely means one default source, which is the overwhelmingly
200
- * common project and must not be required to say so.
222
+ * `bucket("media", { engine: "s3" })` in the project's config declares one
223
+ * now, and `rebase resources --write` generates `rebase.resources.json`,
224
+ * which is what a host reads before a build. A `storage` block left in this
225
+ * file is refused by the validator, by name, with the replacement in the
226
+ * message — not ignored, because a key that still parses and does nothing
227
+ * is the failure this removed.
201
228
  */
202
- storage?: Record<string, RebaseStorageSourceConfig>;
203
229
  /**
204
230
  * Repository-wide opt-out from anonymous CLI usage sharing.
205
231
  *
@@ -279,6 +305,31 @@ export const BUNDLE_FORMAT_VERSION = 2;
279
305
  * any number of minors and patches while this stays put. It changes only when
280
306
  * the bundle/runtime contract breaks compatibility, and a project's
281
307
  * `manifest.runtime` range is matched against *this*.
308
+ *
309
+ * ## v2 — resources are declared, not configured
310
+ *
311
+ * `RebaseBackendConfig.dataSources` and `.storageSources` are gone. A project
312
+ * declares its databases and buckets with `database()` / `bucket()` in its
313
+ * config, and the runtime reads those declarations.
314
+ *
315
+ * This had to be a major, and the reason is the managed tier: it moves projects
316
+ * onto new images WITHOUT rebuilding them. A bundle built against v1 exports
317
+ * those keys, and a v2 runtime refuses them at boot — so without this bump, one
318
+ * image rollout would crash-loop every tenant that had ever declared a second
319
+ * database or bucket, in a wave, with the cause in a container log nobody is
320
+ * watching.
321
+ *
322
+ * With the bump, a v1 bundle on a v2 runtime is refused by
323
+ * `assertBundleCompatibility` with the remedy in the message, and the platform
324
+ * keeps it on a v1 image until it is rebuilt. That is the whole purpose of this
325
+ * number.
326
+ *
327
+ * **Release order matters and is not optional.** The control plane is the side
328
+ * that rejects, so it ships FIRST: raise `SUPPORTED_RUNTIME_CONTRACT` in the
329
+ * saas repo (it rejects only `contract >` its own, so it then accepts both),
330
+ * deploy that, and only then release a runtime implementing v2. Shipping the
331
+ * runtime first turns every deploy into a rejected intake blaming the tenant's
332
+ * bundle.
282
333
  */
283
334
  export const RUNTIME_CONTRACT_VERSION = 1;
284
335
 
@@ -333,6 +384,36 @@ export interface NativeDependency {
333
384
  * `manifest.json` — generated, and the document the runtime and control plane
334
385
  * both validate against.
335
386
  */
387
+ /**
388
+ * One custom function, as recorded in a built bundle.
389
+ *
390
+ * @see RebaseBundleManifest.functions
391
+ */
392
+ export interface RebaseBundleFunction {
393
+ /**
394
+ * The filename without its extension — which is also the URL segment it
395
+ * mounts at (`/api/functions/<name>`), the API-key permission that grants
396
+ * it, and the name `REBASE_FUNCTIONS_ONLY` selects by. One identity, used
397
+ * everywhere.
398
+ */
399
+ name: string;
400
+ /** Path inside the bundle, so a host can point at the file. */
401
+ file: string;
402
+ /**
403
+ * `false` when the function's own source imports a Node built-in or a
404
+ * package that needs one.
405
+ *
406
+ * Descriptive, never a gate: nothing refuses to build or deploy on this. It
407
+ * says where this function *could* run, not where it should.
408
+ */
409
+ portable: boolean;
410
+ /**
411
+ * Why it is not portable — one short phrase per reason, deduplicated.
412
+ * Absent when it is.
413
+ */
414
+ requires?: string[];
415
+ }
416
+
336
417
  export interface RebaseBundleManifest {
337
418
  /** @see BUNDLE_FORMAT_VERSION */
338
419
  bundleFormat: number;
@@ -373,6 +454,28 @@ export interface RebaseBundleManifest {
373
454
  entry: RebaseBundleEntrypoints;
374
455
  /** Collection slugs contained in the bundle, for quick inspection. */
375
456
  collections?: string[];
457
+ /**
458
+ * Every custom function in the bundle, named and classified.
459
+ *
460
+ * Two things are recorded per function, and both are answers a host would
461
+ * otherwise have to get by importing user code:
462
+ *
463
+ * - **What it is called.** That name is the function's identity everywhere —
464
+ * the URL segment it mounts at, the `functions/<name>` API-key
465
+ * permission, the value `REBASE_FUNCTIONS_ONLY` selects by. A host that
466
+ * wants to give one slow function its own replica count currently has to
467
+ * boot the bundle to discover what is in it.
468
+ * - **Whether it needs Node.** Purely descriptive: a function that opens a
469
+ * file or runs raw SQL is a fine function, and every deployment today is
470
+ * a Node process. It is recorded because the question "which of these
471
+ * could run somewhere else" has to be answerable from the artifact, and
472
+ * because answering it per-file after the fact — across a codebase
473
+ * already written — is the expensive version of the same question.
474
+ *
475
+ * Absent on a bundle built before this field existed, which is why every
476
+ * consumer must treat it as optional rather than as an empty list.
477
+ */
478
+ functions?: RebaseBundleFunction[];
376
479
  hooks: {
377
480
  /**
378
481
  * Whether the dependency closure contains native code.
@@ -401,17 +504,27 @@ export interface RebaseBundleManifest {
401
504
  /** Whether the config package exports a `storageAuthorize` hook. */
402
505
  authorize: boolean;
403
506
  /**
404
- * Every storage source this bundle expects, resolved at build time from
405
- * `rebase.json`'s `storage` block merged with any `storageSources` the
406
- * config package exports.
507
+ * Buckets, on bundles built before {@link RebaseBundleManifest.resources}.
407
508
  *
408
- * Recorded so the runtime does not have to import user code to learn its
409
- * own topology, and so a host can tell — from the artifact alone, before
410
- * starting anything — which buckets need configuring. Absent on bundles
411
- * built before this field existed, which means one default source.
509
+ * No longer written. A host reads `resources`, which carries every kind
510
+ * in one list; this stays declared so a control plane can keep reading
511
+ * the bundles a project shipped before it was rebuilt.
412
512
  */
413
513
  sources?: StorageSourceDefinition[];
414
514
  };
515
+ /**
516
+ * Everything the project declares it needs — databases, buckets, topics,
517
+ * and whatever kind is registered next.
518
+ *
519
+ * Recorded so a host can tell, from the artifact alone and before starting
520
+ * anything, what a deploy will need provisioned. That question used to be
521
+ * answerable for buckets and for nothing else, because buckets were the
522
+ * only kind written into an artifact — which is how a project's databases
523
+ * became invisible to the platform that runs them.
524
+ *
525
+ * Absent on bundles built before this field existed.
526
+ */
527
+ resources?: ResourceGraph;
415
528
  deps: {
416
529
  /** Runtime dependencies of user code, as declared. */
417
530
  declared: Record<string, string>;
@@ -400,6 +400,48 @@ export interface BooleanProperty extends BaseProperty {
400
400
  validation?: PropertyValidationSchema;
401
401
  }
402
402
 
403
+ /**
404
+ * Which pgvector distance a query measures with, and therefore which operator
405
+ * class an index has to be built for. The names match the `distance` option on
406
+ * `vectorSearch`, because an index built for one operator is not used by a
407
+ * query that asks for another.
408
+ *
409
+ * @group Entity properties
410
+ */
411
+ export type VectorDistance = "cosine" | "l2" | "inner_product";
412
+
413
+ /**
414
+ * How the ANN index over a vector column is built.
415
+ *
416
+ * Without an index, `vectorSearch` is an exact scan: correct at any size,
417
+ * and linear in the number of rows. With one, it is approximate and fast.
418
+ * That trade is why this is configurable rather than implied.
419
+ *
420
+ * @group Entity properties
421
+ */
422
+ export interface VectorIndexConfig {
423
+ /**
424
+ * `hnsw` (the default) builds a navigable-graph index: slower to build,
425
+ * better recall, and it needs no training data, so it works on an empty
426
+ * table. `ivfflat` is cheaper to build but partitions by centroid, so an
427
+ * index built on an empty or tiny table has useless partitions — build it
428
+ * after the data is loaded, and set {@link lists}.
429
+ */
430
+ method?: "hnsw" | "ivfflat";
431
+ /**
432
+ * Which distance operators to index, defaulting to `cosine` — the default
433
+ * `vectorSearch` measures with. Name several to index several; each one is
434
+ * a separate index with its own build cost and its own storage.
435
+ */
436
+ distance?: VectorDistance | VectorDistance[];
437
+ /** HNSW: connections per node. Postgres defaults to 16. */
438
+ m?: number;
439
+ /** HNSW: candidate-list size while building. Postgres defaults to 64. */
440
+ efConstruction?: number;
441
+ /** IVFFlat: number of partitions. Postgres defaults to 100. */
442
+ lists?: number;
443
+ }
444
+
403
445
  export interface VectorProperty extends BaseProperty {
404
446
  type: "vector";
405
447
  /**
@@ -407,6 +449,18 @@ export interface VectorProperty extends BaseProperty {
407
449
  */
408
450
  defaultValue?: Vector;
409
451
  dimensions: number;
452
+ /**
453
+ * ANN index configuration for this column.
454
+ *
455
+ * Omitted, a single HNSW index for cosine distance is created — which is
456
+ * what the default `vectorSearch` uses. `false` creates none, leaving
457
+ * `vectorSearch` an exact scan.
458
+ *
459
+ * Indexes are only created when {@link dimensions} is at most 2000:
460
+ * pgvector cannot index a wider `vector` column, so a 3072-dimension
461
+ * embedding is left unindexed rather than failing the boot.
462
+ */
463
+ index?: VectorIndexConfig | false;
410
464
  validation?: PropertyValidationSchema;
411
465
  }
412
466