@rebasepro/types 0.16.0 → 0.16.1-canary.g041c925

package/dist/types/properties.d.ts

@@ -1,9 +1,9 @@
-import type { Entity, EntityReference, EntityRelation, EntityValues, GeoPoint, Vector } from "./entities";
-import type { Relation, ResolvedRelation } from "./relations";
-import type { ColorKey, ColorScheme } from "./chips";
-import type { AuthState } from "../controllers/auth_state";
-import type { AfterReadProps, BeforeSaveProps } from "./entity_callbacks";
-import type { User } from "../users";
+import type { Entity, EntityReference, EntityRelation, EntityValues, GeoPoint, Vector } from "./entities.js";
+import type { Relation, ResolvedRelation } from "./relations.js";
+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";
 /**
  * Callbacks/Hooks for individual property fields
  * @group Entity properties
@@ -324,6 +324,46 @@ export interface BooleanProperty extends BaseProperty {
      */
     validation?: PropertyValidationSchema;
 }
+/**
+ * Which pgvector distance a query measures with, and therefore which operator
+ * class an index has to be built for. The names match the `distance` option on
+ * `vectorSearch`, because an index built for one operator is not used by a
+ * query that asks for another.
+ *
+ * @group Entity properties
+ */
+export type VectorDistance = "cosine" | "l2" | "inner_product";
+/**
+ * How the ANN index over a vector column is built.
+ *
+ * Without an index, `vectorSearch` is an exact scan: correct at any size,
+ * and linear in the number of rows. With one, it is approximate and fast.
+ * That trade is why this is configurable rather than implied.
+ *
+ * @group Entity properties
+ */
+export interface VectorIndexConfig {
+    /**
+     * `hnsw` (the default) builds a navigable-graph index: slower to build,
+     * better recall, and it needs no training data, so it works on an empty
+     * table. `ivfflat` is cheaper to build but partitions by centroid, so an
+     * index built on an empty or tiny table has useless partitions — build it
+     * after the data is loaded, and set {@link lists}.
+     */
+    method?: "hnsw" | "ivfflat";
+    /**
+     * Which distance operators to index, defaulting to `cosine` — the default
+     * `vectorSearch` measures with. Name several to index several; each one is
+     * a separate index with its own build cost and its own storage.
+     */
+    distance?: VectorDistance | VectorDistance[];
+    /** HNSW: connections per node. Postgres defaults to 16. */
+    m?: number;
+    /** HNSW: candidate-list size while building. Postgres defaults to 64. */
+    efConstruction?: number;
+    /** IVFFlat: number of partitions. Postgres defaults to 100. */
+    lists?: number;
+}
 export interface VectorProperty extends BaseProperty {
     type: "vector";
     /**
@@ -331,6 +371,18 @@ export interface VectorProperty extends BaseProperty {
      */
     defaultValue?: Vector;
     dimensions: number;
+    /**
+     * ANN index configuration for this column.
+     *
+     * Omitted, a single HNSW index for cosine distance is created — which is
+     * what the default `vectorSearch` uses. `false` creates none, leaving
+     * `vectorSearch` an exact scan.
+     *
+     * Indexes are only created when {@link dimensions} is at most 2000:
+     * pgvector cannot index a wider `vector` column, so a 3072-dimension
+     * embedding is left unindexed rather than failing the boot.
+     */
+    index?: VectorIndexConfig | false;
     validation?: PropertyValidationSchema;
 }
 /**

package/dist/types/relations.d.ts

@@ -1,4 +1,4 @@
-import type { AnyCollectionConfig } from "./collections";
+import type { AnyCollectionConfig } from "./collections.js";
 /**
  * @group Models
  */

package/dist/types/resource_kinds.d.ts

@@ -0,0 +1,174 @@
+/**
+ * The kinds Rebase ships, and the constructors a project declares them with.
+ *
+ * Each kind is registered rather than hardcoded, so a fourth one arrives
+ * without editing a manifest schema, a validator and a switch statement. That
+ * cost is precisely why databases and buckets ended up declared in different
+ * files with different rules — the cheapest thing to do was always to bolt the
+ * new kind onto whichever home was nearest.
+ *
+ * A kind owns its engine list. `custom:<id>` is always accepted, so a build
+ * that ships an engine this package has never heard of says so at the call site
+ * instead of looking like a typo of one that exists.
+ */
+import { type DeclareOptions, type ResourceHandle, type ResourceTransport } from "./resources.js";
+/** Options a database accepts beyond the common ones. */
+export interface DatabaseOptions extends DeclareOptions {
+    /**
+     * The physical database or schema within the engine, when it differs from
+     * the engine's own default. Threaded to drivers as `databaseId`.
+     */
+    databaseId?: string;
+    /** Directory of migration files, relative to the config directory. */
+    migrations?: string;
+}
+/** A database handle. Collections point at it via `dataSource`. */
+export type DatabaseHandle = ResourceHandle;
+/**
+ * Declare a database.
+ *
+ * ```ts
+ * export const main      = database();               // the default one
+ * export const analytics = database("analytics");    // reads DATABASE_URL__ANALYTICS
+ * ```
+ */
+export declare function database(key?: string, options?: DatabaseOptions): DatabaseHandle;
+/** Options a bucket accepts beyond the common ones. */
+export interface BucketOptions extends DeclareOptions {
+    /**
+     * Whether objects are world-readable by default.
+     *
+     * Declared rather than inferred from the engine, because the two have
+     * disagreed before: a private object served through a cacheable public URL
+     * is a data leak that nothing errors on.
+     */
+    publicRead?: boolean;
+    /** Key prefix within the bucket, for sharing one bucket between sources. */
+    prefix?: string;
+}
+/** A bucket handle. Storage properties point at it via `storageSource`. */
+export type BucketHandle = ResourceHandle;
+/**
+ * Declare a bucket.
+ *
+ * ```ts
+ * export const media = bucket("media", { transport: "direct" });
+ * ```
+ *
+ * `transport: "direct"` means a provider SDK talks to the bucket and the
+ * backend is not in the upload path.
+ */
+export declare function bucket(key?: string, options?: BucketOptions): BucketHandle;
+/**
+ * How hard the runtime tries to deliver.
+ *
+ * Only `at-least-once` is implemented, and it is the honest name for what a
+ * retrying queue does: a handler must tolerate seeing the same event twice.
+ * `at-most-once` is listed so a future transport can offer it without the
+ * option changing shape, and is refused today rather than silently upgraded.
+ */
+export type TopicDelivery = "at-least-once" | "at-most-once";
+/** Options a topic accepts beyond the common ones. */
+export interface TopicOptions extends DeclareOptions {
+    delivery?: TopicDelivery;
+    /** Attempts per subscription before a message is left failed. Default 5. */
+    maxAttempts?: number;
+}
+/**
+ * What a subscription does with an event.
+ *
+ * `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.
+ */
+export type TopicHandler<T> = (event: T, context: {
+    attempt: number;
+    topic: string;
+    subscription: string;
+}) => Promise<void> | void;
+/** A declared subscription, as recorded in the graph and wired at boot. */
+export interface TopicSubscription<T = unknown> {
+    topic: string;
+    name: string;
+    handler: TopicHandler<T>;
+    maxAttempts?: number;
+}
+/**
+ * What a topic publishes through.
+ *
+ * Installed by `@rebasepro/server` at boot. Absent — in the CLI evaluating
+ * config to derive the graph, or in a unit test — publishing throws a message
+ * naming the cause, rather than resolving and dropping the event. A publish
+ * that silently does nothing is the failure mode a queue exists to prevent.
+ */
+export interface TopicRuntime {
+    publish(topic: string, event: unknown): Promise<void>;
+}
+/** Install the transport topics publish through. Called by the server at boot. */
+export declare function setTopicRuntime(runtime: TopicRuntime | null): void;
+/** Every declared subscription, for the worker to wire and the graph to record. */
+export declare function declaredSubscriptions(topic?: string): TopicSubscription[];
+/** Forget declared subscriptions. For tests, alongside `resetDeclaredResources`. */
+export declare function resetDeclaredSubscriptions(): void;
+/** A topic handle, carrying its payload type. */
+export interface TopicHandle<T> extends ResourceHandle {
+    /**
+     * Publish an event.
+     *
+     * Resolves once the event is durably recorded for every subscription, not
+     * once they have run. Enqueued inside a transaction that rolls back, it was
+     * never published.
+     */
+    publish(event: T): Promise<void>;
+    /**
+     * Declare a subscription.
+     *
+     * The name is its identity: it is what the job row records, what a retry
+     * counts against, and what a second subscription must not collide with.
+     */
+    subscription(name: string, handler: TopicHandler<T>, options?: {
+        maxAttempts?: number;
+    }): void;
+}
+/**
+ * Declare a topic.
+ *
+ * ```ts
+ * export const signups = topic<{ userId: string }>("signups");
+ * signups.subscription("send-welcome", async (event) => { … });
+ * await signups.publish({ userId });
+ * ```
+ */
+export declare function topic<T = unknown>(key: string, options?: TopicOptions): TopicHandle<T>;
+/**
+ * The declared databases, in the shape `<Rebase dataSources>` takes.
+ *
+ * The frontend needs to know which sources exist and how they are reached — a
+ * `direct`-transport source is one the browser talks to itself — and it imports
+ * the same config package the backend does. Without these it would mean writing
+ * the list a second time, by hand, next to the declarations, which is precisely
+ * the two-homes problem this model removed everywhere else.
+ *
+ * ```tsx
+ * import "../config/resources";                 // registers them
+ * import { declaredDataSources, declaredStorageSources } from "@rebasepro/types";
+ *
+ * <Rebase dataSources={declaredDataSources()} storageSources={declaredStorageSources()} />
+ * ```
+ *
+ * The import is what registers them, so a bundler that drops an unused module
+ * would leave this empty — hence the side-effect import above rather than a
+ * bare re-export.
+ */
+export declare function declaredDataSources(): {
+    key: string;
+    engine: string;
+    transport: ResourceTransport;
+    label?: string;
+}[];
+/** The declared buckets, in the shape `<Rebase storageSources>` takes. */
+export declare function declaredStorageSources(): {
+    key: string;
+    engine: string;
+    transport: ResourceTransport;
+    label?: string;
+}[];

package/dist/types/resources.d.ts

@@ -0,0 +1,197 @@
+/**
+ * The resource graph: one declaration site for every named thing a project needs.
+ *
+ * ## The rule
+ *
+ * **Every named resource is declared with a constructor in config code.** A
+ * database, a bucket, a topic and whatever kind comes next are all spelled the
+ * same way, so "where do I declare my second one" has one answer instead of one
+ * answer per kind.
+ *
+ * ```ts
+ * export const main    = database("main");
+ * export const media   = bucket("media", { transport: "direct" });
+ * export const signups = topic<SignupEvent>("signups");
+ * ```
+ *
+ * ## Declaration is not binding
+ *
+ * A declaration says a resource *exists* and what shape it has. It never says
+ * how to reach it — that is a property of the environment, not of the project,
+ * and it differs between a laptop, a self-hosted box and a tenant in the cloud.
+ * Binding lives in `@rebasepro/server`'s boot path, reading environment
+ * variables or an infrastructure config file, and it keys off the logical name
+ * declared here.
+ *
+ * This split is the whole point. Before it, storage topology was hand-written
+ * into `rebase.json` while database topology lived in TypeScript, and the
+ * boundary between them was a fact about what the control plane could read
+ * before a build — a platform implementation detail that a developer had no way
+ * to derive. Worse, storage could be declared in *both* places, and the merge
+ * silently kept the JSON's engine and discarded the code's.
+ *
+ * ## Why a registry rather than a fixed union
+ *
+ * Kinds register themselves. Adding pub/sub, a cache or a search index must not
+ * require editing a manifest schema, a validator and three switch statements —
+ * that cost is exactly why the last two kinds ended up in different homes.
+ */
+/** How a client reaches a resource. */
+export type ResourceTransport = 
+/** Through the backend. The default, and the only one that needs no client SDK. */
+"server"
+/** A provider SDK talks to the resource directly; the backend is not in the path. */
+ | "direct";
+/**
+ * A resource kind, as registered.
+ *
+ * `engines` is an allowlist rather than documentation. An unrecognised engine
+ * used to be a free string that passed every check and failed later, further
+ * from the typo that caused it — `"s2"` for `"s3"` reached the runtime. Anything
+ * genuinely outside the list is spelled `custom:<id>`, which says so at the call
+ * site instead of looking like a typo.
+ */
+export interface ResourceKindSpec {
+    /** The kind's name, as it appears in a declaration and in the graph. */
+    kind: string;
+    /** Engines this kind ships with. `custom:<id>` is always additionally valid. */
+    engines: readonly string[];
+    /** Used when a declaration names none. */
+    defaultEngine: string;
+    /**
+     * Environment variable base names this kind binds from, in the order a
+     * binder should try them. A resource keyed `analytics` reads
+     * `<BASE>__ANALYTICS`; the default-keyed resource reads `<BASE>` unsuffixed,
+     * so a single-resource project configured the obvious way declares nothing.
+     */
+    envBases: readonly string[];
+    /**
+     * The subset of `envBases` that matters for a given engine.
+     *
+     * The binder reads every base and takes whichever is set — harmless, and it
+     * keeps binding tolerant. A GENERATOR cannot be that relaxed: `rebase eject
+     * infra` writing S3_BUCKET, GCS_BUCKET, STORAGE_BUCKET and
+     * STORAGE_PUBLIC_URL for a `local` bucket hands somebody four variables of
+     * which three are noise, and a config file full of irrelevant keys is one
+     * nobody reads carefully.
+     *
+     * Keyed by engine; an engine with no entry falls back to all of them, which
+     * is the honest answer for one this package has never heard of.
+     */
+    envBasesByEngine?: Readonly<Record<string, readonly string[]>>;
+    /** Option keys this kind accepts beyond the common ones, for validation. */
+    optionKeys?: readonly string[];
+    /**
+     * Whether a project implicitly has one of these even when it declares
+     * nothing. True for databases — a backend without one is not a backend —
+     * and false for topics, where zero is the normal number.
+     */
+    implicitDefault?: boolean;
+}
+/** The key a resource takes when a project declares only one of its kind. */
+export declare const DEFAULT_RESOURCE_KEY = "(default)";
+/** A declared resource, as it appears in the graph. */
+export interface ResourceDeclaration {
+    kind: string;
+    /** Unique within its kind. What a binder looks up and what an env suffix is built from. */
+    key: string;
+    engine: string;
+    transport: ResourceTransport;
+    label?: string;
+    /** Kind-specific options, validated against the kind's `optionKeys`. */
+    options: Readonly<Record<string, unknown>>;
+}
+/**
+ * The value a constructor returns.
+ *
+ * Carries its own declaration so config code can hold it and pass it around,
+ * and stringifies to its key so it drops into the places that still take one.
+ * Collections name a data source by string today; a handle works there without
+ * the collection API having to change, which keeps this a config redesign
+ * rather than a rewrite of the data layer.
+ */
+export interface ResourceHandle extends ResourceDeclaration {
+    toString(): string;
+}
+/** Whether a value is a resource handle rather than a plain string key. */
+export declare function isResourceHandle(value: unknown): value is ResourceHandle;
+/** The key a resource reference names, whether it is a handle or already a key. */
+export declare function resourceKeyOf(ref: string | ResourceHandle): string;
+/** Register a resource kind. Idempotent for an identical spec; throws on a conflicting one. */
+export declare function registerResourceKind(spec: ResourceKindSpec): void;
+/** Every registered kind, for validators and for `rebase doctor`. */
+export declare function resourceKinds(): ResourceKindSpec[];
+/** One registered kind, or undefined. */
+export declare function resourceKind(kind: string): ResourceKindSpec | undefined;
+/** Options every kind accepts. */
+export interface DeclareOptions {
+    engine?: string;
+    transport?: ResourceTransport;
+    label?: string;
+    [option: string]: unknown;
+}
+/** Whether an engine is one the kind knows, or an explicit `custom:` opt-out. */
+export declare function isValidEngine(spec: ResourceKindSpec, engine: string): boolean;
+/**
+ * Declare a resource. The primitive every kind's constructor is built from.
+ *
+ * Redeclaring the same `kind:key` with a *different* shape throws rather than
+ * merging. Merging is what the old storage path did, and it silently discarded
+ * one of the two engines — a declaration accepted and then ignored, which is
+ * the failure this whole model exists to remove. Redeclaring it identically is
+ * fine: a config module evaluated twice must not be an error.
+ */
+export declare function declareResource(kind: string, key?: string, options?: DeclareOptions): ResourceHandle;
+/** Every declared resource, in declaration order, optionally filtered by kind. */
+export declare function declaredResources(kind?: string): ResourceDeclaration[];
+/**
+ * Forget every declaration, keeping registered kinds.
+ *
+ * For tests and for a CLI that evaluates more than one project in a process.
+ * Kinds survive because they are registered by module import, which will not
+ * happen a second time.
+ */
+export declare function resetDeclaredResources(): void;
+/**
+ * The env-var suffix a resource's bindings use: `__ANALYTICS` for `analytics`,
+ * and nothing at all for the default-keyed one.
+ *
+ * The default takes no suffix so that a project with one database configured
+ * through plain `DATABASE_URL` keeps working having declared nothing — the
+ * overwhelmingly common project must not have to say so.
+ */
+export declare function resourceEnvSuffix(key: string): string;
+/**
+ * Two resources of a kind whose keys differ but whose env suffixes do not.
+ *
+ * `media-files` and `media_files` both become `__MEDIA_FILES`, so one would
+ * silently read the other's configuration. Returned rather than thrown so the
+ * caller can report it with the rest of a validation pass.
+ */
+export declare function findEnvSuffixCollision(keys: readonly string[]): {
+    a: string;
+    b: string;
+    suffix: string;
+} | null;
+/**
+ * The whole graph, as recorded in a manifest and read by a host.
+ *
+ * `version` is the graph format, not the project's. A host reading a graph it
+ * does not understand must say so rather than provision half of it.
+ */
+export interface ResourceGraph {
+    version: 1;
+    resources: ResourceDeclaration[];
+}
+/** The current graph format version. */
+export declare const RESOURCE_GRAPH_VERSION: 1;
+/** Build a graph from the current declarations, sorted for a stable diff. */
+export declare function buildResourceGraph(): ResourceGraph;
+/**
+ * The environment variables worth writing for a resource, given its engine.
+ *
+ * Falls back to every base the kind reads when the engine is unknown — a
+ * `custom:` engine gets the full list rather than an empty one, because
+ * guessing narrow would silently omit the variable it actually needs.
+ */
+export declare function envBasesForResource(declaration: ResourceDeclaration): readonly string[];

package/dist/types/schema_editing.d.ts

@@ -0,0 +1,127 @@
+/**
+ * The vocabulary a live schema change is described in.
+ *
+ * Declared here, and nowhere else, because two packages that must not import
+ * each other both need it: `@rebasepro/server-postgres` decides what a change
+ * means and renders the files it needs, while `@rebasepro/server` commits those
+ * files and serves the routes. Neither can reach the other — the server is
+ * engine-agnostic by design — so the shared kernel holds the shapes and the
+ * driver is detected structurally through {@link SchemaEditingAdmin}.
+ *
+ * Nothing here executes anything. These are the nouns.
+ */
+/**
+ * What a change will do to a live database.
+ *
+ * - `safe` — the boot-time ensure path expresses it, and the result matches the
+ *   configuration.
+ * - `diverges` — the ensure path applies *something*, but the database will not
+ *   match what the configuration declares, and nothing reports it. This is the
+ *   category worth having: adding a required property to a populated table
+ *   yields a nullable column, and adding a value to an existing enum yields
+ *   nothing at all. Both read as success.
+ * - `needs-migration` — the ensure path cannot express it. Dropping anything,
+ *   changing a type, moving a primary key.
+ */
+export type SchemaChangeVerdict = "safe" | "diverges" | "needs-migration";
+export type SchemaChangeKind = "add-collection" | "remove-collection" | "add-property" | "remove-property" | "change-property-type" | "rename-column" | "add-enum-value" | "remove-enum-value" | "change-required" | "change-primary-key";
+export interface SchemaChange {
+    kind: SchemaChangeKind;
+    verdict: SchemaChangeVerdict;
+    /** Collection slug. */
+    collection: string;
+    /** Property name, where the change is to one. */
+    property?: string;
+    /** One line, specific: what changed and what it will do. */
+    detail: string;
+    /** What to do instead, when the verdict is not `safe`. */
+    remedy?: string;
+}
+export interface ClassifiedSchemaChanges {
+    changes: SchemaChange[];
+    /** The worst verdict present, or `safe` for an empty diff. */
+    verdict: SchemaChangeVerdict;
+    /** True only when every change is `safe` — the one case an editor may apply. */
+    applicable: boolean;
+}
+/**
+ * Where a project's generated schema artifacts live, relative to the **project**
+ * root — which is the repository root only when the project is the whole
+ * repository.
+ *
+ * Here rather than in the Postgres package because it is a contract, not an
+ * engine detail: `@rebasepro/server` has to derive these for a project in a
+ * subdirectory, and it cannot import a driver to do it.
+ */
+export interface SchemaCommitPaths {
+    /** Drizzle schema, imported by the backend. */
+    schemaFile: string;
+    /** Declarative DDL, what `db push` applies and Atlas diffs against. */
+    ddlFile: string;
+    policiesFile: string;
+    searchFile: string;
+}
+export declare const DEFAULT_COMMIT_PATHS: SchemaCommitPaths;
+/** One file the commit writes, as content rather than as a path on a disk. */
+export interface SchemaChangeFile {
+    path: string;
+    contents: string;
+}
+/**
+ * Everything a change needs written and run.
+ *
+ * Computed without touching a disk or a network. The database is *read* — what
+ * a change means depends on what is already there, and a plan that guessed
+ * would be guessing about whether the statements it returns will be accepted.
+ */
+export interface SchemaChangePlan {
+    /** Every file the commit writes — collection source and generated artifacts. */
+    files: SchemaChangeFile[];
+    /** The additive DDL this change adds, in dependency order. */
+    statements: string[];
+    classified: ClassifiedSchemaChanges;
+    /** A commit message describing the change rather than announcing one. */
+    message: string;
+    /**
+     * Constraints the configuration asks for that these statements do not
+     * carry, and why.
+     *
+     * Almost always empty. When it is not, it is the part the person confirming
+     * needs to read: the change will apply, and the database will still not
+     * enforce something the configuration says — a required property over a
+     * table that already holds rows with no value for it. Optional so a plan
+     * from an engine that does not distinguish these cases stays valid.
+     */
+    withheldConstraints?: WithheldSchemaConstraint[];
+}
+/** A constraint a plan asks for and does not apply. */
+export interface WithheldSchemaConstraint {
+    /** `schema.table.column`. */
+    target: string;
+    kind: "not-null";
+    /** What is in the way, naming the obstacle rather than the rule. */
+    reason: string;
+    /** What would make it applicable. */
+    remedy: string;
+}
+/**
+ * An admin that can plan a schema change.
+ *
+ * Planning only. Applying is `executeSql`, which every SQL admin already has,
+ * and committing belongs to whatever holds the repository — keeping those three
+ * apart is what lets the same plan be committed locally on a developer's machine
+ * and through a GitHub App from a cloud tenant.
+ *
+ * @group Admin
+ */
+export interface SchemaEditingAdmin {
+    /**
+     * Decide what the change means and render everything it needs.
+     *
+     * Rejects when the change is not applicable, carrying the classification so
+     * a caller can say which change was the problem.
+     */
+    planSchemaChange(before: unknown[], after: unknown[], options?: {
+        paths?: Partial<SchemaCommitPaths>;
+    }): Promise<SchemaChangePlan>;
+}

package/dist/types/schema_version.d.ts

@@ -1,4 +1,4 @@
-import type { CollectionConfig } from "./collections";
+import type { CollectionConfig } from "./collections.js";
 /**
  * Compute the canonical string a schema version hashes.
  *

package/dist/types/security_rules.d.ts

@@ -15,7 +15,7 @@
  * them with `getPolicyNamesForRule`/`getEffectiveSecurityRules` rather than
  * matching on `rule.name`.
  */
-import type { PolicyExpression } from "./policy";
+import type { PolicyExpression } from "./policy.js";
 /**
  * SQL operation that a policy applies to.
  * @group Models

package/dist/users/index.d.ts

@@ -1 +1 @@
-export * from "./user";
+export * from "./user.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/types",
   "type": "module",
-  "version": "0.16.0",
+  "version": "0.16.1-canary.g041c925",
   "description": "Rebase type definitions — shared interfaces and controller types",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -88,7 +88,7 @@
   },
   "scripts": {
     "watch": "vite build --watch",
-    "build": "vite build && tsc --emitDeclarationOnly -p tsconfig.prod.json && node ../../scripts/assert-build-output.mjs",
+    "build": "vite build && tsc --emitDeclarationOnly -p tsconfig.prod.json && node ../../tooling/scripts/add-dts-extensions.mjs dist && node ../../tooling/scripts/assert-build-output.mjs",
     "test:lint": "eslint \"src/**\" --quiet",
     "test": "jest --passWithNoTests",
     "clean": "rm -rf dist && find ./src -name '*.js' -type f | xargs rm -f"

package/src/controllers/client.ts

@@ -300,7 +300,7 @@ export interface RebaseClient<DB = unknown> {
     /** Unified Authentication layer */
     auth: AuthClient;
 
-    /** Unified Storage layer (default storage source, backward-compatible) */
+    /** Unified Storage layer — the default storage source. */
     storage?: StorageSource;
 
     /** Registry of all named storage sources for multi-backend support */
@@ -437,6 +437,19 @@ export interface RebaseServerClient<DB = unknown> extends Omit<RebaseClient<DB>,
      * Execute raw SQL against the database. Always present server-side for SQL
      * engines. Values interpolated into the query should be passed via
      * `params`, referenced as `$1`, `$2`, … placeholders in the query text.
+     *
+     * **Runtime note.** This is the one accessor on this object that is not
+     * portable. It runs on the database owner connection over a TCP socket, so
+     * it is available wherever the framework holds that connection — every Node
+     * deployment, self-hosted or managed — and not on a host that has no
+     * sockets and no business holding owner credentials.
+     *
+     * Nothing about that is a problem for a Node deployment, and it is not a
+     * reason to avoid it there. It is a reason not to build a function's *only*
+     * data path on it if that function may later move: `c.get("driver")` and
+     * `rebase.dataAsAdmin` go over the same wire wherever they run. A function
+     * that genuinely needs raw SQL can ask `runtimeKey()` and degrade, rather
+     * than discovering it at the call.
      */
     sql(query: string, options?: { database?: string; role?: string; params?: unknown[] }): Promise<Record<string, unknown>[]>;
 }

package/src/controllers/data.ts

@@ -3,15 +3,6 @@ import type { ComputedSortField, SearchMatch } from "../types/search";
 import { Entity, EntityValues } from "../types/entities";
 import { WhereFilterOp, FieldPath, FilterValues, OrderBySpec } from "../types/filter-operators";
 
-/**
- * Operator-blind filter value: whatever the column holds, a list of it, or null.
- *
- * @deprecated Superseded by {@link WhereValueFor}, which correlates the value
- * with the operator. Kept exported because it is public API and downstream code
- * annotates with it; every `where()` overload in this file uses `WhereValueFor`.
- */
-export type WhereValue<T> = T | T[] | null;
-
 /**
  * The element type of an array column, and the column's own type otherwise.
  *