@rebasepro/common 0.12.0 → 0.12.1-canary.g009ed95

package/dist/util/auth-default-policies.d.ts

@@ -20,3 +20,21 @@ export declare function getEffectiveSecurityRules(collection: CollectionConfig):
  * DDL, which policies are injected and how to take them off.
  */
 export declare function getInjectedSecurityRules(collection: CollectionConfig): SecurityRule[];
+/**
+ * Every policy name `rebase db push` would write for a collection.
+ *
+ * This is the answer to "did the codebase produce this live policy?", and it is
+ * more than `securityRules.map(r => r.name)` for two reasons:
+ *
+ *  - a rule without an explicit `name` compiles to `<table>_<op>_<hash>`, one
+ *    per operation, so comparing `rule.name` to `policyname` never matches it;
+ *  - the generator also injects the safe-by-default baseline
+ *    (`<table>_default_admin_*`), which is in no collection's `securityRules`.
+ *
+ * Every UI that flags drift has to get both right, and each one that derived it
+ * by hand got a different subset — which is how four policies *Rebase itself
+ * wrote* came to be badged as hand-written drift on every table in a project,
+ * with a button offering to import them back into the codebase that produced
+ * them. There is one derivation now, and this is it.
+ */
+export declare function getGeneratedPolicyNames(collection: CollectionConfig): Set<string>;

package/dist/util/builders.d.ts

@@ -1,14 +1,4 @@
-import { ArrayProperty, BooleanProperty, DateProperty, CollectionConfig, FirebaseCollectionConfig, FirebaseProperties, GeopointProperty, InferEntityType, MapProperty, MongoDBCollectionConfig, MongoProperties, NumberProperty, PostgresCollectionConfig, PostgresProperties, Property, ReferenceProperty, StringProperty, User } from "@rebasepro/types";
-/**
- * @deprecated Use {@link defineCollection} instead — it infers property
- * types automatically (autocomplete on `titleProperty`, `sort`,
- * `propertiesOrder`, callbacks) without manual generics.
- * `buildCollection` is kept for FireCMS migration compatibility and will
- * be removed before 1.0.
- *
- * @group Builder
- */
-export declare function buildCollection<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>(collection: CollectionConfig<M, USER>): CollectionConfig<M, USER>;
+import { FirebaseCollectionConfig, FirebaseProperties, InferEntityType, MongoDBCollectionConfig, MongoProperties, PostgresCollectionConfig, PostgresProperties, User } from "@rebasepro/types";
 /**
  * Define a PostgreSQL-backed collection with full type inference.
  *
@@ -56,12 +46,3 @@ export declare function defineCollection<const P extends MongoProperties, USER e
 }): MongoDBCollectionConfig<InferEntityType<P>, USER> & {
     properties: P;
 };
-/**
- * @deprecated Use plain typed property objects with {@link defineCollection}
- * instead — `defineCollection` infers property types automatically, making
- * this wrapper unnecessary. `buildProperty` is kept for FireCMS migration
- * compatibility and will be removed before 1.0.
- *
- * @group Builder
- */
-export declare function buildProperty<T, P extends Property = Property>(property: P): P extends StringProperty ? StringProperty : P extends NumberProperty ? NumberProperty : P extends BooleanProperty ? BooleanProperty : P extends DateProperty ? DateProperty : P extends GeopointProperty ? GeopointProperty : P extends ReferenceProperty ? ReferenceProperty : P extends ArrayProperty ? ArrayProperty : P extends MapProperty ? MapProperty : never;

package/dist/util/email.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Email normalization — one implementation, because the database enforces it.
+ *
+ * `ensureAuthTablesExist` puts a `UNIQUE INDEX ON users (lower(email))` on the
+ * auth table. That index decides what "the same address" means, and it does not
+ * trim: to Postgres, `' foo@bar.com'` and `'foo@bar.com'` are two addresses and
+ * both may exist. So every write that reaches the column has to agree with
+ * every read, exactly, or the two disagree in the one direction that matters —
+ * a row that exists and cannot be found.
+ *
+ * That is not hypothetical. The lookup path trimmed and the admin create paths
+ * did not, so a user created through `POST /api/data/users` or
+ * `POST /api/auth/admin/users` with a stray space was stored untrimmed,
+ * survived the unique index alongside the real address, and was unreachable by
+ * login forever after. The HTTP auth routes were unaffected only because Zod's
+ * `.email()` happens to reject surrounding whitespace — a guard on a different
+ * layer, for a different reason, that the admin paths do not sit behind.
+ *
+ * It lives in `common` because `server`, `server-postgres` and `server-mongo`
+ * all write this column and must agree exactly, and `common` is the only
+ * package all three already depend on.
+ */
+/**
+ * Canonical form of an email address: trimmed, lower-cased.
+ *
+ * Non-strings pass through untouched, so this is safe to apply to a value out
+ * of a partial update payload whose type is not known yet.
+ */
+export declare function normalizeEmail<T>(email: T): T | string;

package/dist/util/index.d.ts

@@ -2,6 +2,7 @@ export * from "./collections";
 export * from "./common";
 export * from "./entities";
 export * from "./identity";
+export * from "./email";
 export * from "./enums";
 export * from "./paths";
 export * from "./resolutions";
@@ -16,3 +17,4 @@ export * from "./auth-default-policies";
 export * from "./junction-policies";
 export * from "./conditions";
 export * from "./pg-column-to-property";
+export * from "./string-column-length";

package/dist/util/policy/sqlToPolicy.d.ts

@@ -18,7 +18,12 @@ export interface AnonymousGrantRisk {
  * is how the trusted *server* context is recognised), so:
  *
  *  - `auth.uid() IS NOT NULL` is a tautology on the user path, and
- *  - `auth.uid() != 'anon'` compares against a string no caller ever has.
+ *  - `auth.uid() != 'anon'` excludes one spelling of anonymous and admits the
+ *    other. This one is not hypothetical and was not only a foreign habit:
+ *    rebase's own request path reported `'anon'` while everything that compiled
+ *    or checked a policy used `'anonymous'`, so whichever literal an author
+ *    picked, half the anonymous callers walked through. See
+ *    {@link ANONYMOUS_USER_IDS}.
  *
  * Either one turns a lockdown into a full grant, and neither looks wrong. No
  * real user id is ever one of these literals, and a user-context request is

package/dist/util/string-column-length.d.ts

@@ -0,0 +1,24 @@
+import type { StringProperty } from "@rebasepro/types";
+/**
+ * The length a bounded string column is declared with when the property does
+ * not say. Historical: it is what the DDL generator hardcoded, kept so that
+ * regenerating an existing schema does not silently redefine its columns.
+ */
+export declare const DEFAULT_STRING_COLUMN_LENGTH = 255;
+/**
+ * How wide a `varchar`/`char` column should be for a given property.
+ *
+ * One definition, three call sites, because they used to disagree. For the same
+ * `columnType: "varchar"` property the DDL generator emitted `VARCHAR(255)`
+ * while the Drizzle generator emitted a bare `varchar("col")` — which Postgres
+ * reads as *unbounded* — so which of the two you ran decided whether the column
+ * had a limit at all. Introspection then dropped the length entirely, so reading
+ * an existing `character varying(500)` column back and regenerating it produced
+ * a `VARCHAR(255)`: a silent narrowing of a column with data already in it.
+ *
+ * `validation.max` is the property's own statement about how long the value may
+ * be, so it is the only sensible source for the column's width — and it keeps
+ * the constraint the database enforces in step with the one the app enforces,
+ * rather than inventing a second, different limit underneath it.
+ */
+export declare function resolveStringColumnLength(prop: Pick<StringProperty, "validation">): number;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/common",
   "type": "module",
-  "version": "0.12.0",
+  "version": "0.12.1-canary.g009ed95",
   "description": "Awesome Firebase/Firestore-based headless open-source CMS",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -38,26 +38,26 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "fast-equals": "6.0.0",
+    "fast-equals": "6.0.2",
     "json-logic-js": "^2.0.5",
-    "@rebasepro/types": "0.12.0",
-    "@rebasepro/utils": "0.12.0"
+    "@rebasepro/utils": "0.12.1-canary.g009ed95",
+    "@rebasepro/types": "0.12.1-canary.g009ed95"
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",
     "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.1",
     "@types/jest": "^30.0.0",
-    "@types/node": "^25.9.3",
+    "@types/node": "^26.1.2",
     "@types/object-hash": "^3.0.6",
     "@types/react-measure": "^2.0.12",
     "babel-plugin-react-compiler": "beta",
     "cross-env": "^10.1.0",
     "jest": "^30.4.2",
-    "ts-jest": "^29.4.11",
+    "ts-jest": "^29.4.12",
     "tsd": "^0.33.0",
     "typescript": "^6.0.3",
-    "vite": "^8.0.16"
+    "vite": "^8.1.5"
   },
   "files": [
     "dist",

package/src/data/buildRebaseData.ts

@@ -99,7 +99,7 @@ function rowToEntity<M extends Record<string, unknown>>(
 }
 
 /**
- * The relation envelope `toCmsRow` writes where a relation was:
+ * The relation envelope `toFlatRow` writes where a relation was:
  * `{ id, path, __type: "relation", data: { id, path, values } }`. It is the
  * admin's view-model, and the only pipeline that produces one is postgres'.
  */

package/src/util/auth-default-policies.ts

@@ -1,5 +1,6 @@
 import { CollectionConfig, SecurityRule, SecurityOperation, AuthCollectionConfig, PolicyExpression, isPostgresCollectionConfig, policy } from "@rebasepro/types";
 import { getTableName } from "./relations";
+import { getPolicyNamesForRules } from "@rebasepro/utils";
 
 /**
  * Default RLS policies injected by the schema generator.
@@ -150,3 +151,24 @@ export function getInjectedSecurityRules(collection: CollectionConfig): Security
     // so everything past the author's count is injected.
     return getEffectiveSecurityRules(collection).slice(explicitCount);
 }
+
+/**
+ * Every policy name `rebase db push` would write for a collection.
+ *
+ * This is the answer to "did the codebase produce this live policy?", and it is
+ * more than `securityRules.map(r => r.name)` for two reasons:
+ *
+ *  - a rule without an explicit `name` compiles to `<table>_<op>_<hash>`, one
+ *    per operation, so comparing `rule.name` to `policyname` never matches it;
+ *  - the generator also injects the safe-by-default baseline
+ *    (`<table>_default_admin_*`), which is in no collection's `securityRules`.
+ *
+ * Every UI that flags drift has to get both right, and each one that derived it
+ * by hand got a different subset — which is how four policies *Rebase itself
+ * wrote* came to be badged as hand-written drift on every table in a project,
+ * with a button offering to import them back into the codebase that produced
+ * them. There is one derivation now, and this is it.
+ */
+export function getGeneratedPolicyNames(collection: CollectionConfig): Set<string> {
+    return getPolicyNamesForRules(getEffectiveSecurityRules(collection), getTableName(collection));
+}

package/src/util/builders.ts

@@ -1,43 +1,16 @@
 import {
-    ArrayProperty,
-    BooleanProperty,
-    DateProperty,
     CollectionConfig,
     FirebaseCollectionConfig,
     FirebaseProperties,
-    GeopointProperty,
     InferEntityType,
-    MapProperty,
     MongoDBCollectionConfig,
     MongoProperties,
-    NumberProperty,
     PostgresCollectionConfig,
     PostgresProperties,
-    Property,
-    ReferenceProperty,
-    StringProperty,
     User
 } from "@rebasepro/types";
 
 
-/**
- * @deprecated Use {@link defineCollection} instead — it infers property
- * types automatically (autocomplete on `titleProperty`, `sort`,
- * `propertiesOrder`, callbacks) without manual generics.
- * `buildCollection` is kept for FireCMS migration compatibility and will
- * be removed before 1.0.
- *
- * @group Builder
- */
-export function buildCollection<
-    M extends Record<string, unknown> = Record<string, unknown>,
-    USER extends User = User>
-    (
-        collection: CollectionConfig<M, USER>
-    ): CollectionConfig<M, USER> {
-    return collection;
-}
-
 // ── defineCollection ─────────────────────────────────────────────────────
 // A smarter builder that uses `const` type-parameter inference (TS 5.0+)
 // to capture literal property types automatically. This gives you
@@ -107,26 +80,3 @@ export function defineCollection(
     return collection;
 }
 
-/**
- * @deprecated Use plain typed property objects with {@link defineCollection}
- * instead — `defineCollection` infers property types automatically, making
- * this wrapper unnecessary. `buildProperty` is kept for FireCMS migration
- * compatibility and will be removed before 1.0.
- *
- * @group Builder
- */
-export function buildProperty<T, P extends Property = Property>(
-    property: P
-):
-    P extends StringProperty ? StringProperty :
-    P extends NumberProperty ? NumberProperty :
-    P extends BooleanProperty ? BooleanProperty :
-    P extends DateProperty ? DateProperty :
-    P extends GeopointProperty ? GeopointProperty :
-    P extends ReferenceProperty ? ReferenceProperty :
-    P extends ArrayProperty ? ArrayProperty :
-    P extends MapProperty ? MapProperty : never {
-
-    // SAFETY: Identity function — P is a subtype of the conditional return type by definition
-    return property as unknown as ReturnType<typeof buildProperty<T, P>>;
-}

package/src/util/email.ts

@@ -0,0 +1,32 @@
+/**
+ * Email normalization — one implementation, because the database enforces it.
+ *
+ * `ensureAuthTablesExist` puts a `UNIQUE INDEX ON users (lower(email))` on the
+ * auth table. That index decides what "the same address" means, and it does not
+ * trim: to Postgres, `' foo@bar.com'` and `'foo@bar.com'` are two addresses and
+ * both may exist. So every write that reaches the column has to agree with
+ * every read, exactly, or the two disagree in the one direction that matters —
+ * a row that exists and cannot be found.
+ *
+ * That is not hypothetical. The lookup path trimmed and the admin create paths
+ * did not, so a user created through `POST /api/data/users` or
+ * `POST /api/auth/admin/users` with a stray space was stored untrimmed,
+ * survived the unique index alongside the real address, and was unreachable by
+ * login forever after. The HTTP auth routes were unaffected only because Zod's
+ * `.email()` happens to reject surrounding whitespace — a guard on a different
+ * layer, for a different reason, that the admin paths do not sit behind.
+ *
+ * It lives in `common` because `server`, `server-postgres` and `server-mongo`
+ * all write this column and must agree exactly, and `common` is the only
+ * package all three already depend on.
+ */
+
+/**
+ * Canonical form of an email address: trimmed, lower-cased.
+ *
+ * Non-strings pass through untouched, so this is safe to apply to a value out
+ * of a partial update payload whose type is not known yet.
+ */
+export function normalizeEmail<T>(email: T): T | string {
+    return typeof email === "string" ? email.trim().toLowerCase() : email;
+}

package/src/util/index.ts

@@ -2,6 +2,7 @@ export * from "./collections";
 export * from "./common";
 export * from "./entities";
 export * from "./identity";
+export * from "./email";
 export * from "./enums";
 export * from "./paths";
 export * from "./resolutions";
@@ -16,3 +17,4 @@ export * from "./auth-default-policies";
 export * from "./junction-policies";
 export * from "./conditions";
 export * from "./pg-column-to-property";
+export * from "./string-column-length";

package/src/util/permissions.test.ts

@@ -148,13 +148,27 @@ roles: ["admin", "editor"] }
         expect(canReadCollection(collection, adminAuthController)).toBe(true); // admin
     });
 
-    test("10. Roles on user are objects {id, name} — correctly mapped to strings", () => {
+    // The test that used to sit here claimed roles arrive as `{ id, name }`
+    // objects and are mapped to strings. `User.roles` is `string[]` and no such
+    // mapping exists anywhere, so the fixture was plain strings and the
+    // assertion was test 9 again with a different rule. What is worth pinning
+    // instead is that the match is an exact string membership test.
+    test("10. Role IDs match exactly — not by prefix, substring or case", () => {
         const collection = createMockCollection([
             { operation: "select",
 roles: ["author"] }
         ]);
-        // mockUser.roles = [{ id: "author" }, { id: "user" }]
-        expect(canReadCollection(collection, mockAuthController)).toBe(true);
+        const withRoles = (roles: string[] | undefined): AuthState<User> => ({
+            user: { ...mockUser,
+roles }
+        });
+
+        expect(canReadCollection(collection, withRoles(["author", "user"]))).toBe(true);
+        expect(canReadCollection(collection, withRoles(["authors"]))).toBe(false);
+        expect(canReadCollection(collection, withRoles(["auth"]))).toBe(false);
+        expect(canReadCollection(collection, withRoles(["Author"]))).toBe(false);
+        expect(canReadCollection(collection, withRoles([]))).toBe(false);
+        expect(canReadCollection(collection, withRoles(undefined))).toBe(false);
     });
 
     test("11. Empty roles array [] adds no role restriction (public rule stays public)", () => {

package/src/util/pg-column-to-property.ts

@@ -42,6 +42,7 @@ function pgTypeToRebaseProperty(column: TableColumnInfo): Property | null {
         udt_name,
         is_nullable,
         column_default,
+        character_maximum_length,
         enum_values
     } = column;
 
@@ -78,11 +79,23 @@ label: prettifyIdentifier(v) })),
             let colType: "varchar" | "text" | "char" = "varchar";
             if (dt === "text" || dt === "citext") colType = "text";
             if (dt === "char" || dt === "character") colType = "char";
+            // Carry the declared width across. Dropping it made introspection
+            // lossy in the one direction that costs data: a `character
+            // varying(500)` column read back as a bare `varchar` regenerates as
+            // `VARCHAR(255)`, narrowing a column that already holds longer
+            // values. TEXT has no width, and reporting one would invent a limit
+            // the database does not have.
+            const declaredLength = colType === "text" ? null : character_maximum_length;
             const prop: StringProperty = {
                 type: "string",
                 name: prettifiedName,
                 columnType: colType,
-                validation: required ? { required: true } : undefined
+                validation: required || declaredLength
+                    ? {
+                        ...(required ? { required: true } : {}),
+                        ...(declaredLength ? { max: declaredLength } : {})
+                    }
+                    : undefined
             };
             if (isAutoId) {
                 prop.isId = "manual";

package/src/util/policy/evaluatePolicy.ts

@@ -1,4 +1,4 @@
-import { ANONYMOUS_USER_ID, Entity, PolicyCompareOperator, PolicyExpression, PolicyOperand } from "@rebasepro/types";
+import { ANONYMOUS_USER_ID, isAnonymousUid, Entity, PolicyCompareOperator, PolicyExpression, PolicyOperand } from "@rebasepro/types";
 
 /**
  * Result of evaluating a policy client-side. `"unknown"` means the expression
@@ -61,7 +61,11 @@ export function evaluatePolicy(expr: PolicyExpression, ctx: PolicyEvalContext):
             return expr.roles.every(r => r === "public" || userRoles.includes(r));
         }
         case "authenticated":
-            return ctx.uid != null && ctx.uid !== ANONYMOUS_USER_ID;
+            // Every anonymous spelling, matching what this node compiles to in
+            // Postgres — the two evaluators disagreeing about who is signed in
+            // is the client optimistically rendering a row the database will
+            // refuse, or hiding one it would have allowed.
+            return ctx.uid != null && !isAnonymousUid(ctx.uid);
         case "serverContext":
             // A client is never the server context. Postgres decides this by
             // `auth.uid() IS NULL`, which a client request can never produce:

package/src/util/policy/policyToPostgres.ts

@@ -1,4 +1,4 @@
-import { ANONYMOUS_USER_ID, CollectionConfig, PolicyExpression, PolicyOperand, PolicyCompareOperator, Property, ExistsInPolicyExpression } from "@rebasepro/types";
+import { ANONYMOUS_USER_IDS, CollectionConfig, PolicyExpression, PolicyOperand, PolicyCompareOperator, Property, ExistsInPolicyExpression } from "@rebasepro/types";
 import { toSnakeCase } from "@rebasepro/utils";
 import { getTableName } from "../relations";
 
@@ -88,9 +88,15 @@ function compile(expr: PolicyExpression, scope: CompileScope): string {
         case "authenticated":
             // `IS NOT NULL` alone is a tautology on the user path: every
             // user-context request sets `app.uid`, and an anonymous one sets
-            // it to the sentinel. Excluding the sentinel is what makes this mean
+            // it to a sentinel. Excluding the sentinels is what makes this mean
             // "signed in" rather than "anyone at all".
-            return `auth.uid() IS NOT NULL AND auth.uid() <> ${quoteLiteral(ANONYMOUS_USER_ID)}`;
+            //
+            // Every sentinel, not just the current one. This clause is written
+            // into the database and outlives the server that generated it: a
+            // policy compiled here may be enforced against an older server that
+            // still reports `'anon'`, which is exactly how excluding one
+            // spelling turned this helper into a grant. See ANONYMOUS_USER_IDS.
+            return `auth.uid() IS NOT NULL AND auth.uid() NOT IN (${ANONYMOUS_USER_IDS.map(quoteLiteral).join(", ")})`;
         case "serverContext":
             // Only the built-in server flows leave `app.uid` unset.
             return "auth.uid() IS NULL";

package/src/util/policy/sqlToPolicy.ts

@@ -1,4 +1,4 @@
-import { ANONYMOUS_USER_ID, LiteralPolicyOperand, PolicyExpression, policy } from "@rebasepro/types";
+import { ANONYMOUS_USER_ID, ANONYMOUS_USER_IDS, LiteralPolicyOperand, PolicyExpression, policy } from "@rebasepro/types";
 
 /**
  * A tiny, regex-based SQL "parser" for security rules.
@@ -185,7 +185,12 @@ const UID_NOT_NULL = /auth\.uid\(\)\s+IS\s+NOT\s+NULL/i;
  * is how the trusted *server* context is recognised), so:
  *
  *  - `auth.uid() IS NOT NULL` is a tautology on the user path, and
- *  - `auth.uid() != 'anon'` compares against a string no caller ever has.
+ *  - `auth.uid() != 'anon'` excludes one spelling of anonymous and admits the
+ *    other. This one is not hypothetical and was not only a foreign habit:
+ *    rebase's own request path reported `'anon'` while everything that compiled
+ *    or checked a policy used `'anonymous'`, so whichever literal an author
+ *    picked, half the anonymous callers walked through. See
+ *    {@link ANONYMOUS_USER_IDS}.
  *
  * Either one turns a lockdown into a full grant, and neither looks wrong. No
  * real user id is ever one of these literals, and a user-context request is
@@ -231,7 +236,9 @@ export function findAnonymousGrants(expr: PolicyExpression): AnonymousGrantRisk[
                     detail: literal.value,
                     explanation: `'${literal.value}' is a ${platform} convention. Rebase reports an anonymous ` +
                         `request as '${ANONYMOUS_USER_ID}', so comparing against '${literal.value}' passes for ` +
-                        "every caller. Use `condition: policy.authenticated()` to mean \"signed in\"."
+                        "every caller. Use `condition: policy.authenticated()` to mean \"signed in\" — it " +
+                        `compiles to NOT IN (${ANONYMOUS_USER_IDS.map(v => `'${v}'`).join(", ")}), covering ` +
+                        "every spelling rebase has reported rather than whichever one you remember."
                 });
                 return;
             }

package/src/util/resolve-relation.ts

@@ -37,13 +37,7 @@ export function resolveRelation(
         );
     }
 
-    const targetCollection = target();
-    if (!targetCollection?.slug) {
-        throw new Error(
-            `Relation${relation.relationName ? ` '${relation.relationName}'` : ""} on ` +
-            `'${sourceCollection.slug}' has a \`target\` that did not resolve to a collection.`
-        );
-    }
+    const targetCollection = callTarget(relation, sourceCollection, propertyKey, target);
 
     // The name is the address: the `include` key, the admin tab, and the
     // segment of a nested path. Declared name wins, then the declaring
@@ -80,7 +74,8 @@ export function resolveRelation(
                 cardinality: "one",
                 writable: true,
                 shared: false,
-                foreignKeyOnTarget: relation.foreignKeyOnTarget ?? generateForeignKeyName(sourceName)
+                foreignKeyOnTarget: relation.foreignKeyOnTarget ?? generateForeignKeyName(sourceName),
+                sourceKey: relation.sourceKey
             };
 
         case "hasMany":
@@ -90,7 +85,11 @@ export function resolveRelation(
                 cardinality: "many",
                 writable: true,
                 shared: false,
-                foreignKeyOnTarget: relation.foreignKeyOnTarget ?? generateForeignKeyName(sourceName)
+                foreignKeyOnTarget: relation.foreignKeyOnTarget ?? generateForeignKeyName(sourceName),
+                // Not defaulted: the source's primary key needs the driver's
+                // schema to resolve, which resolution does not have. `undefined`
+                // means "the primary key" — see `ResolvedHasMany.sourceKey`.
+                sourceKey: relation.sourceKey
             };
 
         case "manyToMany": {
@@ -132,3 +131,69 @@ export function resolveRelation(
         }
     }
 }
+
+/** How this relation is addressed in an error message, before it has a resolved name. */
+function describe(relation: Relation, sourceCollection: CollectionConfig, propertyKey?: string): string {
+    const name = relation.relationName ?? propertyKey;
+    return `Relation${name ? ` '${name}'` : ""} on '${sourceCollection.slug}'`;
+}
+
+/**
+ * Call the `target` thunk, and translate the two ways an import cycle breaks it
+ * into an error that names the cause.
+ *
+ * The thunk exists to defer the reference until every module has finished
+ * evaluating, and for a cycle that closes at import time it does. What it cannot
+ * defer is a cycle that leaves the binding permanently unusable, and there are
+ * two shapes of that:
+ *
+ *  - **ESM/TDZ.** `const` and `class` bindings in a not-yet-evaluated module are
+ *    in the temporal dead zone, so reading one throws `ReferenceError: x is not
+ *    defined`. The stack points at the thunk — a one-line arrow function that is
+ *    obviously fine — and says nothing about the cycle that made it throw.
+ *  - **CJS interop.** The half-initialised module object has no `default` yet,
+ *    the import resolves to `undefined`, and the thunk returns it without
+ *    complaint. That one used to surface here as "did not resolve to a
+ *    collection", which is true and unhelpful.
+ *
+ * Both mean the same thing, and the fix for both is the same: break the cycle,
+ * or move the relation into the collection that does not close it.
+ */
+function callTarget(
+    relation: Relation,
+    sourceCollection: CollectionConfig,
+    propertyKey: string | undefined,
+    target: Relation["target"]
+): ReturnType<Relation["target"]> {
+    let targetCollection: ReturnType<Relation["target"]> | undefined;
+    try {
+        targetCollection = target();
+    } catch (error) {
+        // A ReferenceError from inside the thunk is a binding that was never
+        // initialised — nothing else in a one-expression arrow can raise one.
+        if (error instanceof ReferenceError) {
+            throw new Error(
+                `${describe(relation, sourceCollection, propertyKey)} targets a collection that is not ` +
+                `initialized yet — almost always an import cycle between the two collection files. ` +
+                `Break the cycle (move the shared piece into a third module, or import the target ` +
+                `lazily) so the target's module finishes evaluating before the registry is built.`,
+                { cause: error }
+            );
+        }
+        throw error;
+    }
+
+    if (!targetCollection?.slug) {
+        throw new Error(
+            `${describe(relation, sourceCollection, propertyKey)} has a \`target\` that resolved to ` +
+            `${targetCollection === undefined ? "`undefined`" : "something that is not a collection"}. ` +
+            (targetCollection === undefined
+                ? "Under CommonJS interop an import cycle resolves the default import to `undefined`, " +
+                  "so check whether this collection and its target import each other. Otherwise the thunk " +
+                  "is returning the wrong value — it must return the collection itself, not a promise or a module."
+                : "The thunk must return a collection config with a `slug`.")
+        );
+    }
+
+    return targetCollection;
+}

package/src/util/string-column-length.ts

@@ -0,0 +1,31 @@
+import type { StringProperty } from "@rebasepro/types";
+
+/**
+ * The length a bounded string column is declared with when the property does
+ * not say. Historical: it is what the DDL generator hardcoded, kept so that
+ * regenerating an existing schema does not silently redefine its columns.
+ */
+export const DEFAULT_STRING_COLUMN_LENGTH = 255;
+
+/**
+ * How wide a `varchar`/`char` column should be for a given property.
+ *
+ * One definition, three call sites, because they used to disagree. For the same
+ * `columnType: "varchar"` property the DDL generator emitted `VARCHAR(255)`
+ * while the Drizzle generator emitted a bare `varchar("col")` — which Postgres
+ * reads as *unbounded* — so which of the two you ran decided whether the column
+ * had a limit at all. Introspection then dropped the length entirely, so reading
+ * an existing `character varying(500)` column back and regenerating it produced
+ * a `VARCHAR(255)`: a silent narrowing of a column with data already in it.
+ *
+ * `validation.max` is the property's own statement about how long the value may
+ * be, so it is the only sensible source for the column's width — and it keeps
+ * the constraint the database enforces in step with the one the app enforces,
+ * rather than inventing a second, different limit underneath it.
+ */
+export function resolveStringColumnLength(prop: Pick<StringProperty, "validation">): number {
+    const max = prop.validation?.max;
+    return typeof max === "number" && Number.isInteger(max) && max > 0
+        ? max
+        : DEFAULT_STRING_COLUMN_LENGTH;
+}