@rebasepro/types 0.23.0 → 0.24.1-canary.g19596ef

package/dist/types/cron.d.ts

@@ -1,4 +1,5 @@
 import type { RebaseServerClient } from "../controllers/client.js";
+import type { RegisteredDatabase } from "./register.js";
 /**
  * Cron Job type definitions for Rebase.
  *
@@ -10,7 +11,7 @@ import type { RebaseServerClient } from "../controllers/client.js";
  * A cron job definition file exports this shape as its default export.
  * See the example cron files in `app/backend/crons/` for usage.
  */
-export interface CronJobDefinition {
+export interface CronJobDefinition<DB = RegisteredDatabase> {
     schedule: string;
     /**
      * IANA time zone the schedule is read in, e.g. `"Europe/Madrid"`.
@@ -84,17 +85,22 @@ export interface CronJobDefinition {
      * Receives a context object with the data driver and logger.
      * May return arbitrary JSON-serialisable data stored in the log.
      */
-    handler: (ctx: CronJobContext) => Promise<unknown> | unknown;
+    handler: (ctx: CronJobContext<DB>) => Promise<unknown> | unknown;
 }
 /**
  * Context passed to each cron handler invocation.
  */
-export interface CronJobContext {
+export interface CronJobContext<DB = RegisteredDatabase> {
     /** The job's unique ID (derived from filename). */
     jobId: string;
     /** The current scheduled tick timestamp. */
     scheduledAt: Date;
-    /** A simple logger scoped to this job run. */
+    /**
+     * A simple logger scoped to this job run. Each line is written to the
+     * server log at `info`, with a `cron` field holding the job ID, and kept
+     * with the run's log entry — the first 500 lines or 64 KB of them,
+     * whichever comes first, then one line saying how many more there were.
+     */
     log: (...args: unknown[]) => void;
     /**
      * Aborted when the run exceeds `timeoutSeconds`, or when the server
@@ -152,7 +158,7 @@ export interface CronJobContext {
      *     }
      * });
      */
-    rebase: RebaseServerClient;
+    rebase: RebaseServerClient<DB>;
 }
 export type CronJobRunState = "idle" | "running" | "success" | "error" | "disabled";
 /**
@@ -179,11 +185,43 @@ export interface CronJobStatus {
     lastDurationMs?: number;
     /** Error message from the last failed run. */
     lastError?: string;
-    /** Total number of executions since server start. */
+    /**
+     * Executions in the run history: every process's, read from `cron_logs`
+     * where runs are persisted, and this process's own otherwise.
+     */
     totalRuns: number;
-    /** Total number of failed executions since server start. */
+    /** How many of {@link totalRuns} failed. */
     totalFailures: number;
 }
+/**
+ * A job the scheduler refused, and why.
+ *
+ * It is not a `CronJobStatus`: it has no state, no next run and no counters,
+ * because it was never registered. Reporting it as a job with `state: "error"`
+ * would be a lie in the other direction — nothing is going to run it.
+ */
+export interface RejectedCronJob {
+    id: string;
+    name: string;
+    schedule: string;
+    /** Why it was refused — most often `Expected 5 fields, got 6`. */
+    reason: string;
+}
+/** What the cron listing (`GET /admin/cron`) answers. */
+export interface CronJobListing {
+    /** The registered jobs. */
+    jobs: CronJobStatus[];
+    /**
+     * Cron files that did not become jobs: the files that failed to load,
+     * plus the jobs in {@link rejected}. Absent when there are none. None of
+     * them is scheduled.
+     */
+    skipped?: number;
+    /** The jobs the scheduler refused, by name, with the reason. */
+    rejected?: RejectedCronJob[];
+    /** {@link skipped} and {@link rejected}, in a sentence. */
+    note?: string;
+}
 export type CronLogLevel = "info" | "error" | "warn";
 /**
  * A single execution log entry stored in the in-memory ring buffer.
@@ -208,3 +246,16 @@ export interface CronJobLogEntry {
     /** Whether this was a manual trigger. */
     manual?: boolean;
 }
+/**
+ * The answer to a manual trigger made with `?async=1`
+ * (`client.cron.triggerJob(id, { async: true })`): the run has started and
+ * carries on after the answer. Its outcome is in the run history, as the entry
+ * with `manual: true` and this `startedAt`.
+ */
+export interface CronJobStarted {
+    accepted: true;
+    /** ISO timestamp the run started at — the `startedAt` of its log entry. */
+    startedAt: string;
+    /** The job's status as the run began. */
+    job: CronJobStatus;
+}

package/dist/types/database_adapter.d.ts

@@ -21,7 +21,7 @@
  */
 import type { DataDriver } from "../controllers/data_driver.js";
 import type { CollectionConfig } from "./collections.js";
-import type { CollectionRegistryInterface, DatabaseAdmin, InitializedDriver, RealtimeProvider, RealtimeSocketLimits, BootstrappedAuth } from "./backend.js";
+import type { CollectionRegistryInterface, DatabaseAdmin, InitializedDriver, RealtimeProvider, RealtimeSocketOptions, BootstrappedAuth } from "./backend.js";
 import type { HistoryConfig } from "../controllers/client.js";
 /**
  * A `DatabaseAdapter` provides data persistence for Rebase.
@@ -78,7 +78,7 @@ export interface DatabaseAdapter {
      * socket's frames: it serves the same rows, and without them a frame had
      * neither. Forwarded for the same reason `adapter` is.
      */
-    initializeWebsockets?(server: unknown, realtimeService: RealtimeProvider, driver: DataDriver, config?: unknown, adapter?: import("./auth_adapter.js").AuthAdapter, limits?: RealtimeSocketLimits): Promise<void> | void;
+    initializeWebsockets?(server: unknown, realtimeService: RealtimeProvider, driver: DataDriver, config?: unknown, adapter?: import("./auth_adapter.js").AuthAdapter, limits?: RealtimeSocketOptions): Promise<void> | void;
     /**
      * Ask the database whether it is there, before boot's first real query. See
      * `BackendBootstrapper.verifyConnection` for the contract.
@@ -171,9 +171,11 @@ export interface DatabaseAdapter {
      */
     getAdmin?(driverResult: InitializedDriver): DatabaseAdmin | undefined;
     /**
-     * Mount any database-specific HTTP routes (e.g., custom admin endpoints).
+     * Never called: the server mounts no route on an adapter's behalf. A
+     * driver that needs HTTP routes exports a route factory, and the app
+     * mounts it where it chooses.
      *
-     * Called after all adapters are initialized.
+     * @deprecated Never called. Will be removed in a future release.
      */
     mountRoutes?(app: unknown, basePath: string, driverResult: InitializedDriver): void;
     /**
@@ -196,8 +198,29 @@ export interface DatabaseAdapterInitConfig {
      * name none when this is the default.
      */
     dataSourceKey?: string;
-    /** The shared collection registry to register into. */
-    collectionRegistry: CollectionRegistryInterface;
+    /**
+     * The backend's shared collection registry. No bundled driver reads it —
+     * each builds and returns its own on `InitializedDriver.collectionRegistry`
+     * — so a caller opening a driver on its own (a script, a test) leaves it out.
+     */
+    collectionRegistry?: CollectionRegistryInterface;
+    /**
+     * Whether opening the driver may change the database (default `true`).
+     *
+     * The server's boot owns its schema, so the driver provisions what it needs
+     * while it opens: the restricted role requests run as under RLS, the
+     * branch-metadata table, channel-history tables, change-capture triggers.
+     *
+     * `false` opens it with no DDL of any kind — what a script, a REPL or a
+     * test that only reads and writes rows wants, and what a process that does
+     * not own the schema must ask for. A connection that would bypass
+     * row-level security still sends a user's requests through the restricted
+     * role; when an earlier boot never created that role, those requests fail
+     * rather than run unfiltered. Change capture is not installed
+     * (`realtime.provision` reads as `false`); whether change events are
+     * consumed is still `realtime.subscribe`.
+     */
+    provision?: boolean;
     /**
      * Whether this driver should describe its own schema.
      *
@@ -251,9 +274,12 @@ export interface DatabaseAdapterInitConfig {
      * runtime otherwise refuses to boot without.
      *
      * Absent means both — every caller that predates this field is a
-     * single-process deployment, where both are true.
+     * single-process deployment, where both are true. `false` is a process
+     * that takes no part in realtime at all: nothing installed, nothing
+     * consumed, and its writes not announced to the processes that serve
+     * realtime (a script, a REPL).
      */
-    realtime?: {
+    realtime?: false | {
         /**
          * Consume change events: open the `LISTEN` connection, start CDC or the
          * app-level fallback. False for a process that serves no websockets.

package/dist/types/entities.d.ts

@@ -32,6 +32,17 @@ export interface Entity<M extends Record<string, unknown> = Record<string, unkno
      * and a record fetched by id never has one.
      */
     searchMatches?: SearchMatch[];
+    /**
+     * The version of the row this entity was read at: the `ETag` the read
+     * reported, for a `findById`, a `PATCH` answer or a live row frame. A
+     * form saves with it as `If-Match`, so a write made against a version
+     * someone has since replaced is refused instead of reverting their change.
+     *
+     * Absent for a row from a list, from a cache, or from a server or data
+     * source that does not report versions — a save then is unconditional,
+     * as it always was.
+     */
+    etag?: string;
     /**
      * Which driver this entity belongs to (e.g., 'postgres', 'firestore').
      * If not specified, the default driver is assumed.

package/dist/types/history.d.ts

@@ -27,8 +27,20 @@ export interface EntityHistoryEntry {
     action: "create" | "update" | "delete";
     /** Which fields changed. `null` for creates and deletes. */
     changed_fields: string[] | null;
+    /** The row after the change; for a delete, the row that was deleted. */
     values: Record<string, unknown> | null;
+    /**
+     * On an update, what the changed fields held before it. `null` for creates
+     * and deletes. Which fields it holds depends on {@link format}.
+     */
     previous_values: Record<string, unknown> | null;
+    /**
+     * How the entry was stored. Absent or `1`: `previous_values` is the whole
+     * row before the change. `2`: it holds the `changed_fields` only — a field
+     * that is absent from it was absent before — and every other field is
+     * unchanged, so it is in `values`.
+     */
+    format?: 1 | 2;
     updated_by: string | null;
     /** ISO-8601. A driver storing a native date converts on read. */
     updated_at: string;
@@ -46,7 +58,9 @@ export interface RecordHistoryParams {
     updatedBy?: string | null;
 }
 /**
- * How much history to keep. Pruning runs per row after each write.
+ * How much history to keep. Both rules are applied to a row after each write
+ * to it; `ttlDays` is also applied to every row by an hourly sweep, so the
+ * history of a row nobody writes again (a deleted one) still ages out.
  * @group Backend
  */
 export interface HistoryRetentionConfig {

package/dist/types/index.d.ts

@@ -15,6 +15,7 @@ export * from "./entity_callbacks.js";
 export * from "./websockets.js";
 export * from "./backend.js";
 export * from "./schema_editing.js";
+export * from "./collection_patch.js";
 export * from "./channel_bus.js";
 export * from "./data_source.js";
 export * from "./resources.js";
@@ -27,9 +28,11 @@ export * from "./component_ref.js";
 export * from "./auth_adapter.js";
 export * from "./database_adapter.js";
 export * from "./api_keys.js";
+export * from "./scopes.js";
 export * from "./history.js";
 export * from "./postgres_introspection.js";
 export * from "./project_manifest.js";
 export * from "./collection_contract.js";
 export * from "./schema_version.js";
 export * from "./storage_authorize.js";
+export * from "./register.js";

package/dist/types/project_manifest.d.ts

@@ -83,6 +83,14 @@ export interface RebaseBackendAppConfig {
      * its default export. Default `collections/users`.
      */
     usersCollection?: string;
+    /**
+     * Type server-side data from the generated `Database`. When `true`, every
+     * `rebase generate-sdk` — `rebase dev`'s included, and the first one on a
+     * fresh clone — writes the types and the `Register` declaration to
+     * `<config>/generated/`. `rebase generate-sdk --register` sets it.
+     * Default `false`.
+     */
+    registerDatabase?: boolean;
     /**
      * `runtime: "custom"` only. Dockerfile path relative to the repository root.
      * Default `Dockerfile`.
@@ -132,6 +140,20 @@ export interface RebaseStaticAppConfig {
      * loads and every asset 404s: a blank page with no server error. `rebase
      * build` passes it as `REBASE_APP_BASE` and asserts the emitted HTML honours
      * it. Changing this value requires rebuilding the app.
+     *
+     * **Or a full URL, to give the app a hostname of its own:**
+     * `"https://admin.example.com"`, or `"https://admin.example.com/cms"` for a
+     * path under it. The app then answers only on that hostname, and every app
+     * without one keeps answering on all the others. The URL form is split by
+     * {@link parseAppAddress}: the hostname travels as the bundle's
+     * {@link RebaseBundleStatic.host}, and the path part is what the rules above
+     * (and `REBASE_APP_BASE`) apply to. HTTPS only, with no port, query or
+     * fragment — a hostname is served over TLS by the platform, not chosen per
+     * request.
+     *
+     * On Rebase Cloud the deploy registers the hostname on the project. It is
+     * live once its DNS records verify, which the deploy prints when they don't
+     * yet.
      */
     path?: string;
     /**
@@ -191,6 +213,42 @@ export declare const RESERVED_BACKEND_PREFIXES: readonly ["/api", "/health", "/h
  * that is looser admits paths that will not.
  */
 export declare function reservedPrefixFor(path: string): string | undefined;
+/**
+ * Where a static app answers: on one hostname or all of them, at a path.
+ *
+ * `host` absent is every hostname the project is served on.
+ */
+export interface AppAddress {
+    host?: string;
+    path: string;
+}
+export type AppAddressResult = {
+    ok: true;
+    address: AppAddress;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Split a static app's declared `path` into the hostname it claims and the path
+ * under it.
+ *
+ * `"/admin"` is `{ path: "/admin" }`, returned as written: the path rules
+ * (leading slash, no `..`, reserved prefixes) belong to the caller, which
+ * applies them to the path part of either form. `"https://admin.example.com/cms"`
+ * is `{ host: "admin.example.com", path: "/cms" }`.
+ *
+ * Shared because three parties must read the same value the same way: the CLI
+ * while `rebase.json` is edited, the control plane at deploy intake (a bundle can
+ * come from any CLI, or none), and the runtime choosing which app answers.
+ */
+export declare function parseAppAddress(value: string): AppAddressResult;
+/**
+ * Whether `host` is a public DNS name an app can be given: lowercase labels of
+ * letters, digits and hyphens, at least two of them, not an IP address and not
+ * `localhost`. Internationalised names arrive here already in punycode.
+ */
+export declare function isValidAppHost(host: string): boolean;
 /**
  * One declared storage source, as authored in `rebase.json`.
  *
@@ -375,8 +433,22 @@ export interface RebaseBundleEntrypoints {
 }
 /** One built static app inside a bundle. */
 export interface RebaseBundleStatic {
-    /** Public base path, e.g. `/` or `/admin`. */
+    /** Public base path, e.g. `/` or `/admin`. Always a path, never a URL. */
     path: string;
+    /**
+     * The one hostname this app answers on, lowercase, e.g. `admin.example.com`.
+     *
+     * Absent means every hostname the project is served on, which is what every
+     * app was before this field existed. Present, the app answers only for
+     * requests whose `Host` is exactly this — the path part of its address is
+     * still `path`. At an equal `path`, an app naming the request's hostname
+     * wins over one that does not.
+     *
+     * A runtime that predates this field ignores it and would mount two apps at
+     * the same `path`, so a bundle carrying it must only ever reach a runtime
+     * that reads it. The control plane enforces that at intake.
+     */
+    host?: string;
     /** Bundle-relative directory holding the built assets. */
     dir: string;
     /** Serve `index.html` for unmatched paths under `path`. */

package/dist/types/properties.d.ts

@@ -5,6 +5,12 @@ import type { ColorKey, ColorScheme } from "./chips.js";
 import type { AuthState } from "../controllers/auth_state.js";
 import type { AfterReadProps, BeforeSaveProps } from "./entity_callbacks.js";
 import type { User } from "../users/index.js";
+/**
+ * A SQL expression, written in template form: ``"sql`gen_random_uuid()`"``.
+ * The `sql` and backticks are markup; the text between them is the SQL.
+ * @group Entity properties
+ */
+export type SqlExpression = `sql\`${string}\``;
 /**
  * Callbacks/Hooks for individual property fields
  * @group Entity properties
@@ -372,6 +378,25 @@ export interface BaseProperty<CustomProps = unknown> {
      * ```
      */
     access?: FieldAccess;
+    /**
+     * The database fills this column when a create leaves it empty: a
+     * `NOT NULL DEFAULT <expression>` column such as `gen_random_uuid()`,
+     * `nextval(…)` or `now()`, whose value no property can state.
+     *
+     * A `validation.required` field with it may be left out of a create, by
+     * the admin form and by the API alike, and a create that sends it as `null`
+     * leaves it to the database rather than storing `NULL`. It is still
+     * required when a stored record is edited. The generated SDK's `Insert`
+     * type makes the field optional. Defaults to `false`.
+     *
+     * Give the expression, in the template form `isId` takes
+     * (``databaseDefault: "sql`gen_random_uuid()`"``), and the schema planner
+     * writes it as the column's `DEFAULT`, so `rebase db push` keeps it. `true`
+     * declares a DEFAULT someone else wrote and the planner does not write
+     * one, so a push plans dropping it. "Import from table" and
+     * `rebase schema introspect` set the expression they read.
+     */
+    databaseDefault?: boolean | SqlExpression;
     /**
      * Use this to define dynamic properties that change based on certain conditions
      * or on the entity's values. For example, you can make a field read-only if
@@ -421,8 +446,9 @@ export interface StringProperty extends BaseProperty {
      */
     defaultValue?: string;
     /**
-     * Optional database column type. If not set, it defaults to `varchar` or `uuid` depending on `isId` configuration.
-     * Use `text` for strings with unbound length, `char` for fixed-length strings, or `varchar` for variable-length strings with a limit.
+     * Optional database column type. If not set, it is `text` — or `uuid` for an `isId: "uuid"` key.
+     * `validation.max` does not bound a `text` column; declare `varchar` (or `char`) to get a
+     * width, which is then taken from `validation.max` (255 when it states none).
      */
     columnType?: "varchar" | "text" | "char" | "uuid";
     /**
@@ -435,6 +461,13 @@ export interface StringProperty extends BaseProperty {
      * Drizzle append: `.primaryKey()`
      * UI behavior: Field value cannot be changed after creation.
      *
+     * Marking several properties declares one composite key: the table gets a
+     * single `PRIMARY KEY (a, b)` constraint (Drizzle: `primaryKey({ columns })`)
+     * and a row is addressed by all of its key values, joined in declaration
+     * order — `1:::en_US`. A foreign key cannot point at a composite key, so a
+     * relation or reference into such a collection is refused by the schema
+     * generators.
+     *
      * You can set this to `"manual"` for a user-defined ID, or specify a generation strategy:
      * 'uuid' -> Drizzle `.defaultRandom()` (Postgres gen_random_uuid())
      * Or any other string to act as a raw SQL default expression, written either
@@ -565,6 +598,10 @@ export interface NumberProperty extends BaseProperty {
      * Drizzle append: `.primaryKey()`
      * UI behavior: Field value cannot be changed after creation.
      *
+     * Marking several properties declares one composite key — see
+     * {@link StringProperty.isId}. A column whose value the database does not
+     * generate, such as a foreign key that is part of the key, takes `true`.
+     *
      * You can set this to `"manual"` for a user-defined ID, or specify a generation strategy:
      * 'increment' -> PostgreSQL `INTEGER GENERATED BY DEFAULT AS IDENTITY`.
      * Or any other string to act as a raw SQL default expression, bare or in

package/dist/types/register.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The project-wide registry of generated types, filled by module augmentation.
+ *
+ * Empty by default, and every server-side data surface is untyped while it is:
+ * `context.data`, `rebase.dataAsAdmin`, a cron's `ctx.rebase` and a function's
+ * `ctx.rebase` accept any collection by any name and hand back open records.
+ *
+ * A project that generated its types with `rebase generate-sdk` registers its
+ * `Database` once, in any file the TypeScript program includes:
+ *
+ * ```ts
+ * // src/rebase-env.d.ts — or the top of any module file
+ * import type { Database } from "./generated/database.types";
+ *
+ * declare module "@rebasepro/types" {
+ *     interface Register {
+ *         database: Database;
+ *     }
+ * }
+ * ```
+ *
+ * From then on every one of those surfaces is typed from it: rows, filters,
+ * sorts, `include`, and the inputs `create` and `update` accept. Nothing about
+ * the runtime changes; the registration is a declaration.
+ *
+ * A single function or cron can still name its own type instead —
+ * `defineFunction<Database>(…)`, `defineCron<Database>({…})` — which wins over
+ * the registration.
+ *
+ * @group Data
+ */
+export interface Register {
+}
+/**
+ * The `Database` a project registered on {@link Register}, or `unknown` when it
+ * registered none — which is what keeps an unregistered project's server-side
+ * data untyped, exactly as it was before the registry existed.
+ *
+ * @group Data
+ */
+export type RegisteredDatabase = Register extends {
+    database: infer DB;
+} ? DB : unknown;

package/dist/types/relations.d.ts

@@ -22,6 +22,23 @@ export type OnAction = "cascade" | "restrict" | "no action" | "set null" | "set
  * @group Models
  */
 export declare const JUNCTION_PIVOT_KEY = "_pivot";
+/**
+ * The key a row carries the totals of its counted relations under.
+ *
+ * An include that asks for a count — `include: { tags: { limit: 4, count: true } }`
+ * — serves, beside the (capped) `tags`, how many related rows there are in all:
+ * `{ id: 1, tags: [ …4 rows ], _count: { tags: 37 } }`. One object per row,
+ * keyed by relation name, so counting a second relation adds a key rather than
+ * a second top-level name.
+ *
+ * Leading underscore, like {@link JUNCTION_PIVOT_KEY} and `_matches`: it
+ * describes the read, not the record, and no column or form writes it. A
+ * collection with a property of this name cannot ask for a count — the read
+ * answers 400 rather than writing over the column.
+ *
+ * @group Models
+ */
+export declare const INCLUDE_COUNT_KEY = "_count";
 /**
  * What kind of link a relation is.
  *
@@ -108,6 +125,23 @@ export interface BelongsToRelation extends RelationBase {
      * Defaults to `<relationName>_id`.
      */
     localKey?: string;
+    /**
+     * Whether Rebase creates a btree index on {@link localKey}. Defaults to
+     * `true`.
+     *
+     * Postgres indexes the key a foreign key *points at* but never the column
+     * holding it, so without one every read from the other side seq-scans this
+     * table: a `hasMany`/`hasOne` include, a nested listing such as
+     * `/authors/5/posts`, and the `ON DELETE` check when a target row is
+     * deleted. The derived index is skipped on its own when the column already
+     * leads one — the primary key, a `validation.unique`, or an entry in
+     * `indexes:` — so it never duplicates an index you declared.
+     *
+     * Set `false` for a table so write-heavy that the index costs more than
+     * the lookups it serves, or when you keep an index of your own on the
+     * column outside Rebase's `indexes:` block.
+     */
+    index?: boolean;
 }
 /**
  * The target holds the foreign key, and at most one target row points back.
@@ -234,7 +268,7 @@ export interface ManyToManyRelation extends RelationBase {
          *     through: {
          *         table: "org_members",
          *         properties: {
-         *             role: { type: "string", enum: ["owner", "admin", "member"],
+         *             role: { type: "string", enum: { owner: "Owner", admin: "Admin", member: "Member" },
          *                     defaultValue: "member", validation: { required: true } },
          *             joinedAt: { type: "date", autoValue: "on_create" }
          *         }
@@ -364,6 +398,8 @@ export interface ResolvedBelongsTo extends ResolvedRelationBase {
     shared: false;
     /** Column on this collection's table. */
     localKey: string;
+    /** As authored, with the default filled in — see {@link BelongsToRelation.index}. */
+    index: boolean;
 }
 /** @group Models */
 export interface ResolvedHasOne extends ResolvedRelationBase {

package/dist/types/resource_kinds.d.ts

@@ -94,20 +94,24 @@ export interface BucketOptions extends DeclareOptions {
      * is a data leak that nothing errors on.
      */
     publicRead?: boolean;
-    /** Key prefix within the bucket, for sharing one bucket between sources. */
+    /**
+     * @deprecated Never applied: every object lands at the root of its bucket,
+     * whatever this says, so two sources declaring one bucket share one
+     * namespace. Give each source a bucket of its own (`S3_BUCKET__<KEY>`,
+     * `GCS_BUCKET__<KEY>`, or `STORAGE_PATH__<KEY>` for a local one), or put
+     * the folder in each storage property's `storagePath`. The backend warns
+     * once at boot when it is set. Will be removed in a future release.
+     */
     prefix?: string;
     /**
      * Serve unqualified uploads — a storage property with no `storageSource` —
      * from this bucket.
      *
-     * A project that declares only `bucket("media")` has no default bucket, and
-     * the registry used to promote the one it found with a warning. That is a
-     * decision about where a user's files land, made by the framework, on the
-     * strength of declaration order; it also produced two different
-     * destinations either side of a deploy, because the synthesized local
-     * default is dropped in production and the promotion is not. So it is now
-     * a boot error, and this is one of the two ways to answer it — the other
-     * being `bucket()`, which declares the default bucket itself.
+     * Without it, declaring `bucket("media")` leaves the default source where
+     * it was: on its own `STORAGE_PATH` / `./uploads`, or the bucket the
+     * unsuffixed `S3_BUCKET` / `GCS_BUCKET` names. Mark a named bucket to make
+     * it the default instead; the files the default held before stay where
+     * they are and are no longer served through it.
      */
     default?: boolean;
     /**
@@ -167,11 +171,13 @@ export interface TopicOptions extends DeclareOptions {
  *
  * `attempt` counts from 1. Worth branching on: the first delivery and the
  * fourth are the same call, but the fourth is where it is worth logging loudly.
+ * `signal` is aborted when the attempt runs past the job queue's `timeoutMs`.
  */
 export type TopicHandler<T> = (event: T, context: {
     attempt: number;
     topic: string;
     subscription: string;
+    signal: AbortSignal;
 }) => Promise<void> | void;
 /** A declared subscription, as recorded in the graph and wired at boot. */
 export interface TopicSubscription<T = unknown> {
@@ -279,11 +285,15 @@ export interface QueueOptions extends DeclareOptions {
     /** Attempts before a job is left failed. Default 5. */
     maxAttempts?: number;
 }
-/** What a queue's handler receives. `attempt` counts from 1. */
+/**
+ * What a queue's handler receives. `attempt` counts from 1; `signal` is
+ * aborted when the attempt runs past the job queue's `timeoutMs`.
+ */
 export type QueueHandler<T> = (payload: T, context: {
     attempt: number;
     queue: string;
     jobId: string;
+    signal: AbortSignal;
 }) => Promise<void> | void;
 /** Per-job options at enqueue time. */
 export interface QueueEnqueueOptions {