@rebasepro/types 0.16.0 → 0.16.1-canary.g2d1aec8

package/src/types/project_manifest.ts

@@ -333,6 +333,36 @@ export interface NativeDependency {
  * `manifest.json` — generated, and the document the runtime and control plane
  * both validate against.
  */
+/**
+ * One custom function, as recorded in a built bundle.
+ *
+ * @see RebaseBundleManifest.functions
+ */
+export interface RebaseBundleFunction {
+    /**
+     * The filename without its extension — which is also the URL segment it
+     * mounts at (`/api/functions/<name>`), the API-key permission that grants
+     * it, and the name `REBASE_FUNCTIONS_ONLY` selects by. One identity, used
+     * everywhere.
+     */
+    name: string;
+    /** Path inside the bundle, so a host can point at the file. */
+    file: string;
+    /**
+     * `false` when the function's own source imports a Node built-in or a
+     * package that needs one.
+     *
+     * Descriptive, never a gate: nothing refuses to build or deploy on this. It
+     * says where this function *could* run, not where it should.
+     */
+    portable: boolean;
+    /**
+     * Why it is not portable — one short phrase per reason, deduplicated.
+     * Absent when it is.
+     */
+    requires?: string[];
+}
+
 export interface RebaseBundleManifest {
     /** @see BUNDLE_FORMAT_VERSION */
     bundleFormat: number;
@@ -373,6 +403,28 @@ export interface RebaseBundleManifest {
     entry: RebaseBundleEntrypoints;
     /** Collection slugs contained in the bundle, for quick inspection. */
     collections?: string[];
+    /**
+     * Every custom function in the bundle, named and classified.
+     *
+     * Two things are recorded per function, and both are answers a host would
+     * otherwise have to get by importing user code:
+     *
+     * - **What it is called.** That name is the function's identity everywhere —
+     *   the URL segment it mounts at, the `functions/<name>` API-key
+     *   permission, the value `REBASE_FUNCTIONS_ONLY` selects by. A host that
+     *   wants to give one slow function its own replica count currently has to
+     *   boot the bundle to discover what is in it.
+     * - **Whether it needs Node.** Purely descriptive: a function that opens a
+     *   file or runs raw SQL is a fine function, and every deployment today is
+     *   a Node process. It is recorded because the question "which of these
+     *   could run somewhere else" has to be answerable from the artifact, and
+     *   because answering it per-file after the fact — across a codebase
+     *   already written — is the expensive version of the same question.
+     *
+     * Absent on a bundle built before this field existed, which is why every
+     * consumer must treat it as optional rather than as an empty list.
+     */
+    functions?: RebaseBundleFunction[];
     hooks: {
         /**
          * Whether the dependency closure contains native code.

package/src/types/properties.ts

@@ -400,6 +400,48 @@ 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";
     /**
@@ -407,6 +449,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/src/types/schema_editing.ts

@@ -0,0 +1,154 @@
+/**
+ * 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 const DEFAULT_COMMIT_PATHS: SchemaCommitPaths = {
+    schemaFile: "backend/src/schema.generated.ts",
+    ddlFile: "drizzle/schema.sql",
+    policiesFile: "drizzle/policies.sql",
+    searchFile: "drizzle/search.sql"
+};
+
+/** 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>;
+}