@rebasepro/common 0.13.0 → 0.13.1-canary.g18cfeb7

package/src/util/conditions.ts

@@ -3,8 +3,8 @@ import {
     ArrayProperty,
     AuthState,
     ConditionContext,
+    ConditionRule,
     EnumValueConfig,
-    JsonLogicRule,
     NumberProperty,
     PropertyConditions,
     Property,
@@ -66,9 +66,14 @@ export function registerConditionOperations(): void {
 }
 
 /**
- * Evaluate a JSON Logic rule against the given context.
+ * Evaluate a condition against the given context.
+ *
+ * A condition may be stated as a literal instead of a rule — `hidden: true`
+ * rather than `hidden: { "==": [1, 1] }` — and a literal is already its own
+ * answer, so it is returned rather than handed to the evaluator.
  */
-export function evaluateCondition(rule: JsonLogicRule, context: ConditionContext): unknown {
+export function evaluateCondition(rule: ConditionRule, context: ConditionContext): unknown {
+    if (typeof rule === "boolean") return rule;
     // Ensure operations are registered
     registerConditionOperations();
     return jsonLogic.apply(rule, context);

package/src/util/entities.ts

@@ -143,10 +143,24 @@ export function getRelationFrom<M extends Record<string, unknown>>(entity: Entit
  * have `id` and `path` fields — these are relation-shaped objects from
  * edge cases in the data pipeline (REST fallback, stale cache, custom data source).
  *
+ * When `targetPath` is given, also accepts a bare id. A relation column is a
+ * foreign key, and the REST layer returns it as the scalar it is; only some
+ * fetch paths hydrate it into an object. Which form a caller sees therefore
+ * depends on how the row was loaded, and a caller that only accepted objects
+ * reported half of its own data as a type error. The declared target is the
+ * missing half: with it, an id is a relation that has not been fetched yet.
+ *
  * Returns null if the value cannot be coerced.
  */
-export function normalizeToEntityRelation(value: unknown, propertyType?: string): EntityRelation | null {
+export function normalizeToEntityRelation(value: unknown, propertyType?: string, targetPath?: string): EntityRelation | null {
     if (value instanceof EntityRelation) return value;
+
+    if (targetPath && (typeof value === "string" || typeof value === "number")) {
+        // An empty string is an unset foreign key, not row "".
+        if (value === "") return null;
+        return new EntityRelation(value, targetPath);
+    }
+
     if (!value || typeof value !== "object" || Array.isArray(value)) return null;
 
     const obj = value as Record<string, unknown>;

package/src/util/index.ts

@@ -18,3 +18,4 @@ export * from "./junction-policies";
 export * from "./conditions";
 export * from "./pg-column-to-property";
 export * from "./string-column-length";
+export * from "./internal-tables";

package/src/util/internal-tables.ts

@@ -0,0 +1,154 @@
+/**
+ * The tables Rebase creates for its own bookkeeping, and the SQL that keeps the
+ * end-user role away from them.
+ *
+ * ## Why this exists
+ *
+ * Authenticated requests run as {@link REBASE_USER_ROLE}, and the boot-time role
+ * provisioning grants that role `SELECT, INSERT, UPDATE, DELETE` on every table
+ * in the schemas a project uses — including `rebase`, because a project's own
+ * collections are allowed to live there (the scaffold puts `users` there). It
+ * also sets `ALTER DEFAULT PRIVILEGES`, so a table created *later* by the
+ * migrating role inherits the same grant.
+ *
+ * Every framework-internal table is created later: auth's tables come up during
+ * `initializeAuth`, `api_keys` during route mounting, `cron_logs` when the first
+ * job registers, `idempotency_keys` on the first request that carries a key. So
+ * they all inherited full DML for the end-user role — and none of them enables
+ * row-level security, because none of them is a collection with
+ * `securityRules`. Measured on a freshly provisioned database, `SET ROLE
+ * rebase_user` could read `rebase.refresh_tokens` (session token hashes),
+ * `rebase.mfa_factors` (`secret_encrypted`), `rebase.recovery_codes`, and
+ * `rebase.api_keys` (including its `admin` flag), and insert into
+ * `rebase.app_config`.
+ *
+ * Nothing routes a user-context query at those tables today, so this was not
+ * reachable over the API. That is the wrong thing to depend on: the documented
+ * model is that RLS is the authorization boundary, and these tables sat outside
+ * it. The boundary is now a privilege boundary instead — the role simply cannot
+ * address them.
+ *
+ * ## Why REVOKE rather than ENABLE ROW LEVEL SECURITY
+ *
+ * RLS with no policy denies every row, which is the same outcome, but it is the
+ * *weaker* statement: it leaves the grant in place, so a later policy — or a
+ * `FORCE` flag cleared by some future migration — reopens the table. There is no
+ * row of `refresh_tokens` any end user should ever reach, so the honest encoding
+ * is "this role has no privilege here at all". It also keeps the owner
+ * connection (which auth actually runs on) completely unaffected.
+ *
+ * ## Keeping it true
+ *
+ * `packages/rls-check` scans the `rebase` schema — it used to skip it as a
+ * "platform" schema — and its `rls-disabled` check fires on exactly the
+ * condition this module removes: RLS off *and* a DML grant to a reachable role.
+ * So a table added here without a revoke is caught by `pnpm rls:check`, not by
+ * someone re-reading this file.
+ */
+
+/**
+ * The Postgres role authenticated requests run as.
+ *
+ * Defined here rather than in the Postgres driver because both the driver (which
+ * provisions the role) and this module (which revokes on its behalf) need it,
+ * and a second spelling of a role name is a silent no-op waiting to happen.
+ */
+export const REBASE_USER_ROLE = "rebase_user";
+
+/**
+ * Framework-internal table names, unqualified.
+ *
+ * Deliberately NOT including `users`: the auth user table is also a collection,
+ * with `securityRules`, RLS enabled and policies applied. Users read their own
+ * row through it — revoking there would break sign-in.
+ *
+ * `atlas_schema_revisions` is Atlas's migration ledger, which lands in `rebase`
+ * because `db migrate apply` passes `--revisions-schema rebase`.
+ */
+export const REBASE_INTERNAL_TABLES: readonly string[] = [
+    // auth
+    "user_identities",
+    "refresh_tokens",
+    "password_reset_tokens",
+    "magic_link_tokens",
+    "mfa_factors",
+    "mfa_challenges",
+    "recovery_codes",
+    "app_config",
+    "schema_meta",
+    // platform services
+    "api_keys",
+    "cron_logs",
+    "cron_claims",
+    "idempotency_keys",
+    "entity_history",
+    "branches",
+    // realtime channels — authorization for these lives in the channel rules the
+    // server evaluates before it reads or writes, never in a row policy
+    "channel_messages",
+    "channel_cursors",
+    "channel_presence",
+    // migration bookkeeping
+    "atlas_schema_revisions"
+];
+
+/** Postgres identifiers this module is willing to interpolate. */
+const SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_$]*$/;
+
+/**
+ * A single statement that takes every privilege on `schema.table` away from the
+ * end-user role.
+ *
+ * Wrapped in a `DO` block guarded on `pg_roles` for two reasons, both of which
+ * happen in practice:
+ *
+ *  - the role does not exist when the connection is unprivileged (Rebase then
+ *    relies on native RLS rather than a role switch), and a bare `REVOKE` on a
+ *    missing role is an error, not a no-op;
+ *  - the table may not exist yet — `cron_logs` never appears in a project with
+ *    no cron jobs — and `to_regclass` returning NULL has to be tolerated too.
+ *
+ * One command, so it is safe on handles that speak the extended query protocol
+ * and reject multi-statement strings.
+ */
+export function revokeInternalTableSql(schema: string, table: string): string {
+    if (!SAFE_IDENTIFIER.test(schema)) {
+        throw new Error(`Refusing to build SQL with an unsafe schema name: ${JSON.stringify(schema)}`);
+    }
+    if (!SAFE_IDENTIFIER.test(table)) {
+        throw new Error(`Refusing to build SQL with an unsafe table name: ${JSON.stringify(table)}`);
+    }
+    const qualified = `"${schema}"."${table}"`;
+    return `
+        DO $rebase_revoke$
+        BEGIN
+            IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = '${REBASE_USER_ROLE}')
+               AND to_regclass('${qualified}') IS NOT NULL THEN
+                EXECUTE 'REVOKE ALL ON ${qualified} FROM ${REBASE_USER_ROLE}';
+            END IF;
+        END
+        $rebase_revoke$;
+    `.trim();
+}
+
+/**
+ * Revoke on every internal table in `schema`, one statement at a time.
+ *
+ * Best-effort per table: a connection that does not own one of them (a
+ * pre-provisioned database, a platform-managed ledger) cannot revoke on it, and
+ * that must not take down a boot. The caller decides how loud to be — `onError`
+ * exists so the driver can warn without this module importing a logger.
+ */
+export async function revokeInternalTableAccess(
+    execute: (sql: string) => Promise<unknown>,
+    schema: string,
+    options?: { tables?: readonly string[]; onError?: (table: string, error: unknown) => void }
+): Promise<void> {
+    for (const table of options?.tables ?? REBASE_INTERNAL_TABLES) {
+        try {
+            await execute(revokeInternalTableSql(schema, table));
+        } catch (error) {
+            options?.onError?.(table, error);
+        }
+    }
+}

package/src/util/policy/policyToPostgres.ts

@@ -1,4 +1,4 @@
-import { ANONYMOUS_USER_IDS, CollectionConfig, PolicyExpression, PolicyOperand, PolicyCompareOperator, Property, ExistsInPolicyExpression } from "@rebasepro/types";
+import { ANONYMOUS_USER_IDS, CollectionConfig, PolicyExpression, PolicyOperand, PolicyCompareOperator, Property, ExistsInPolicyExpression, RLS_ROLES_SQL, RLS_UID_SQL, rewriteLegacyRlsFunctions } from "@rebasepro/types";
 import { toSnakeCase } from "@rebasepro/utils";
 import { getTableName } from "../relations";
 
@@ -70,7 +70,7 @@ function compile(expr: PolicyExpression, scope: CompileScope): string {
         case "not":
             return `NOT (${compile(expr.operand, scope)})`;
         case "compare": {
-            // `auth.uid()` returns text; cast the column side so uuid / integer
+            // `rebase.uid()` returns text; cast the column side so uuid / integer
             // id columns compare cleanly instead of failing with
             // "operator does not exist: uuid = text" at CREATE POLICY time.
             const castForAuthUid = (operand: PolicyOperand, sqlText: string, other: PolicyOperand): string =>
@@ -82,9 +82,9 @@ function compile(expr: PolicyExpression, scope: CompileScope): string {
             return `${leftSql} ${COMPARE_SQL[expr.op]} ${rightSql}`;
         }
         case "rolesOverlap":
-            return `string_to_array(auth.roles(), ',') && ${rolesArraySql(expr.roles)}`;
+            return `string_to_array(${RLS_ROLES_SQL}, ',') && ${rolesArraySql(expr.roles)}`;
         case "rolesContain":
-            return `string_to_array(auth.roles(), ',') @> ${rolesArraySql(expr.roles)}`;
+            return `string_to_array(${RLS_ROLES_SQL}, ',') @> ${rolesArraySql(expr.roles)}`;
         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
@@ -96,19 +96,32 @@ function compile(expr: PolicyExpression, scope: CompileScope): string {
             // 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(", ")})`;
+            return `${RLS_UID_SQL} IS NOT NULL AND ${RLS_UID_SQL} 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";
+            return `${RLS_UID_SQL} IS NULL`;
         case "existsIn":
             return compileExistsIn(expr, scope);
-        case "raw":
+        case "raw": {
+            // A project written against a pre-1.0 release may still spell the
+            // helpers `auth.uid()`. Rewritten rather than rejected: the rule
+            // means exactly the same thing, the developer cannot be expected to
+            // have read a changelog mid-deploy, and the alternative is a policy
+            // that compiles cleanly and then denies every row at runtime because
+            // it calls a function that no longer exists.
+            //
+            // The counterpart is `warnOnLegacyRlsFunctions`, which says so once
+            // at boot with the file to edit — silence here would leave the old
+            // spelling working forever and make the migration permanent.
+            const sqlText = rewriteLegacyRlsFunctions(expr.sql);
+
             // Full-power escape hatch: `{column}` denotes a column of the outer
             // RLS row. It must be table-qualified, not bare: raw SQL may open its
             // own subquery over the same table, and there a bare name binds to the
             // inner scope, collapsing `m.x = {x}` into the tautology `m.x = m.x`.
-            return expr.sql.replace(/\{(\w+)\}/g, (_, col) =>
+            return sqlText.replace(/\{(\w+)\}/g, (_, col) =>
                 `${outerQualifier(scope)}${resolveColumnName(col, scope.outerCollection)}`);
+        }
     }
 }
 
@@ -156,9 +169,9 @@ function operandToSql(operand: PolicyOperand, scope: CompileScope): string {
         case "literal":
             return quoteLiteral(operand.value);
         case "authUid":
-            return "auth.uid()";
+            return RLS_UID_SQL;
         case "authRoles":
-            return "string_to_array(auth.roles(), ',')";
+            return `string_to_array(${RLS_ROLES_SQL}, ',')`;
     }
 }
 

package/src/util/policy/sqlToPolicy.ts

@@ -1,4 +1,4 @@
-import { ANONYMOUS_USER_ID, ANONYMOUS_USER_IDS, LiteralPolicyOperand, PolicyExpression, policy } from "@rebasepro/types";
+import { ANONYMOUS_USER_ID, ANONYMOUS_USER_IDS, LiteralPolicyOperand, PolicyExpression, policy, rewriteLegacyRlsFunctions } from "@rebasepro/types";
 
 /**
  * A tiny, regex-based SQL "parser" for security rules.
@@ -38,9 +38,9 @@ function isKeywordAt(upper: string, i: number, keyword: string): boolean {
  *
  * This used to be `sql.split(/ AND /i)`, which tore subqueries in half: the
  * `AND` inside
- *   `EXISTS (SELECT 1 FROM organization_members m WHERE m.org = t.org AND m.user_id = auth.uid())`
+ *   `EXISTS (SELECT 1 FROM organization_members m WHERE m.org = t.org AND m.user_id = rebase.uid())`
  * split the expression, and re-emitting the halves produced
- *   `(EXISTS (...) AND m.user_id = auth.uid())`
+ *   `(EXISTS (...) AND m.user_id = rebase.uid())`
  * where `m` is no longer in scope — SQL that Postgres rejects outright with
  * "missing FROM-clause entry for table". Returning null instead keeps such a
  * clause as a `raw` expression, which round-trips verbatim.
@@ -107,22 +107,32 @@ function stripOuterParens(sql: string): string {
 }
 
 export function sqlToPolicy(sql: string): PolicyExpression {
-    const trimmed = stripOuterParens(sql.trim());
+    // Normalised before anything else looks at it, so every pattern below only
+    // has to know the current spelling. A database migrated by a pre-1.0 release
+    // still holds `auth.uid()` in its policy bodies until the next push or boot
+    // recompiles them — and until then the admin UI reads those bodies back
+    // through here. Without this they parse as opaque `raw`, and the framework's
+    // own policies get badged as hand-written drift.
+    //
+    // Normalising rather than accepting both spellings throughout is deliberate:
+    // it also means a legacy policy that falls through to `raw` is stored in the
+    // new spelling, so editing and saving one in the Studio migrates it.
+    const trimmed = stripOuterParens(rewriteLegacyRlsFunctions(sql).trim());
 
     if (trimmed.toLowerCase() === "true") return policy.true();
     if (trimmed.toLowerCase() === "false") return policy.false();
 
     // Handle roles overlap (&&)
-    // Matches: string_to_array(auth.roles(), ',') && ARRAY['admin', 'editor']
-    const overlapMatch = trimmed.match(/^string_to_array\s*\(\s*auth\.roles\(\)\s*,\s*','\s*\)\s*&&\s*ARRAY\s*\[(.+)\]$/i);
+    // Matches: string_to_array(rebase.roles(), ',') && ARRAY['admin', 'editor']
+    const overlapMatch = trimmed.match(/^string_to_array\s*\(\s*rebase\.roles\(\)\s*,\s*','\s*\)\s*&&\s*ARRAY\s*\[(.+)\]$/i);
     if (overlapMatch) {
         const roles = overlapMatch[1].split(",").map(s => s.trim().replace(/^'|'$/g, ""));
         return policy.rolesOverlap(roles);
     }
 
     // Handle roles containment (@>)
-    // Matches: string_to_array(auth.roles(), ',') @> ARRAY['admin']
-    const containMatch = trimmed.match(/^string_to_array\s*\(\s*auth\.roles\(\)\s*,\s*','\s*\)\s*@>\s*ARRAY\s*\[(.+)\]$/i);
+    // Matches: string_to_array(rebase.roles(), ',') @> ARRAY['admin']
+    const containMatch = trimmed.match(/^string_to_array\s*\(\s*rebase\.roles\(\)\s*,\s*','\s*\)\s*@>\s*ARRAY\s*\[(.+)\]$/i);
     if (containMatch) {
         const roles = containMatch[1].split(",").map(s => s.trim().replace(/^'|'$/g, ""));
         return policy.rolesContain(roles);
@@ -146,12 +156,15 @@ export function sqlToPolicy(sql: string): PolicyExpression {
         }
     }
 
-    // Fallback to raw
-    return policy.raw(sql);
+    // Fallback to raw — the NORMALISED text, not the input. Storing the input
+    // verbatim would mean a legacy policy read out of a database, edited in the
+    // Studio and saved, writes `auth.uid()` back into the project's config: a
+    // call to a function 1.0 no longer creates.
+    return policy.raw(trimmed);
 }
 
 /**
- * Literals from other BaaS platforms that people compare `auth.uid()` against
+ * Literals from other BaaS platforms that people compare `rebase.uid()` against
  * out of habit. Mirrors the driver's `FOREIGN_CONVENTION_ROLES` guard on
  * `pgRoles`, one surface over: the same muscle memory inside a `using:` string
  * is the more dangerous spelling, because it inverts a rule instead of
@@ -173,19 +186,26 @@ export interface AnonymousGrantRisk {
     explanation: string;
 }
 
-/** `auth.uid() IS NOT NULL` in raw SQL, the clause that is always true. */
-const UID_NOT_NULL = /auth\.uid\(\)\s+IS\s+NOT\s+NULL/i;
+/**
+ * `rebase.uid() IS NOT NULL` in raw SQL, the clause that is always true.
+ *
+ * Both schema spellings, because this runs over policy bodies read back from a
+ * database, and one migrated by a pre-1.0 release still holds `auth.uid()`.
+ * A security check that stops recognising a dangerous clause because the
+ * framework renamed a function is a check that silently turns off.
+ */
+const UID_NOT_NULL = /\b(?:rebase|auth)\.uid\(\)\s+IS\s+NOT\s+NULL/i;
 
 /**
  * Find clauses that read as "signed-in users only" but admit anonymous callers.
  *
- * Both spellings come from the same place — Supabase, where `auth.uid()` really
- * is NULL for an anonymous request. Rebase substitutes
+ * Both spellings come from the same place — Supabase, where its own `auth.uid()`
+ * really is NULL for an anonymous request. Rebase substitutes
  * {@link ANONYMOUS_USER_ID} instead (a blank id would read back as NULL, which
  * 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'` excludes one spelling of anonymous and admits the
+ *  - `rebase.uid() IS NOT NULL` is a tautology on the user path, and
+ *  - `rebase.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
@@ -219,7 +239,7 @@ export function findAnonymousGrants(expr: PolicyExpression): AnonymousGrantRisk[
                     found.push({
                         pattern: "uid-not-null",
                         detail: e.sql,
-                        explanation: "`auth.uid() IS NOT NULL` is true for every request that came from a client, " +
+                        explanation: "`rebase.uid() IS NOT NULL` is true for every request that came from a client, " +
                             `including anonymous ones — they carry '${ANONYMOUS_USER_ID}', not NULL. ` +
                             "Use `condition: policy.authenticated()` to mean \"signed in\"."
                     });
@@ -252,11 +272,11 @@ export function findAnonymousGrants(expr: PolicyExpression): AnonymousGrantRisk[
 }
 
 function parseOperand(str: string) {
-    // current_setting('app.uid') or auth.uid(). `app.user_id` is the
+    // current_setting('app.uid') or rebase.uid(). `app.user_id` is the
     // pre-rename spelling and stays parseable: policies are data, so a
     // database provisioned before the rename still holds rules written
     // against it, and round-tripping one must not silently drop the operand.
-    if (/current_setting\s*\(\s*'app\.(uid|user_id)'\s*\)/i.test(str) || /auth\.uid\(\)/i.test(str)) {
+    if (/current_setting\s*\(\s*'app\.(uid|user_id)'\s*\)/i.test(str) || /rebase\.uid\(\)/i.test(str)) {
         return policy.authUid();
     }
 

package/src/util/relations.ts

@@ -66,6 +66,37 @@ export function resolveCollectionRelations(
     return relations;
 }
 
+/**
+ * The path of the collection a relation property points at, derived from the
+ * property alone.
+ *
+ * A preview holds a property and a value and no collection, so it cannot call
+ * `resolveRelationProperty`. It does not need to: both forms that carry a
+ * target — the stamped `resolvedRelation` and the inline `relation` — name it
+ * directly. Only the third form, a relation declared by name in the
+ * collection's `relations` array, is out of reach, and that one has no target
+ * to read without the collection anyway.
+ *
+ * This is what lets a preview render a relation column that arrived as a bare
+ * foreign key: the id says *which* row, the declared target says *which
+ * collection*, and `RelationPreview` fetches the rest. Without it a scalar id
+ * is indistinguishable from a value of the wrong type.
+ */
+export function getRelationTargetPath(property: RelationProperty): string | undefined {
+    const stamped = property.resolvedRelation?.targetSlug;
+    if (stamped) return stamped;
+
+    const target = property.relation?.target;
+    if (typeof target !== "function") return undefined;
+    try {
+        return target()?.slug;
+    } catch (_e) {
+        // A thunk reaching into a module that has not finished initialising:
+        // there is no target to name yet, and a preview is not worth throwing over.
+        return undefined;
+    }
+}
+
 export function getTableName(collection: CollectionConfig): string {
     if (isRelationalCollectionConfig(collection)) {
         return collection.table ?? toSnakeCase(collection.slug) ?? toSnakeCase(collection.name);

package/src/util/resolutions.ts

@@ -261,11 +261,11 @@ export function resolveArrayProperties<M>({
                 ignoreMissingFields,
                 ...props
             });
-            const {
-                values,
-                previousValues,
-                ...rest
-            } = props;
+            // Destructured to be *excluded* from `...rest`, not to be used —
+            // see the comment below. Said explicitly so the discarded-value
+            // ratchet does not carry a finding that is working as intended.
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            const { values, previousValues, ...rest } = props;
             const ofProperty = resolveProperty({ // we don't want to pass the values of the parent entity
                 property: of,
                 ignoreMissingFields,
@@ -449,6 +449,78 @@ singularName: customName } : {})
     return views;
 }
 
+/**
+ * Each of `collection`'s tabs paired with the property that declared it, when a
+ * property declared it: child view key → property key.
+ *
+ * A many-relation can only be declared as a property — that is the documented
+ * and only mechanism — and {@link getEntityChildViews} promotes it to a tab. So
+ * one declaration reaches the panel twice, and neither surface knew about the
+ * other. The form rendered a relation picker beside the tab, and the collection
+ * table rendered *two* columns under one heading: the relation's own column,
+ * showing the child rows, and a jump-to-tab button carrying the same name.
+ *
+ * The pairing is what lets each surface decide which half is redundant, and it
+ * has to be a pairing rather than two sets because the two keys differ whenever
+ * a relation is named. The match is on the resolved `relationName` — the
+ * identity `getEntityChildViews` itself dedupes on — so a relation declared in
+ * `relations` and pointed at by a differently-named property is recognised too.
+ *
+ * A relation with no property of its own is absent here, which is the point: it
+ * has exactly one surface already, and nothing to weigh it against.
+ *
+ * Only top-level properties: a relation nested inside a `map` gets no tab.
+ */
+export function getChildViewDeclaringProperties<M extends Record<string, unknown> = Record<string, unknown>>(
+    collection: CollectionConfig<M>
+): Map<string, string> {
+    const pairs = new Map<string, string>();
+
+    const relationProperties = Object.entries((collection.properties ?? {}) as Record<string, Property>)
+        .filter(([, property]) => property?.type === "relation");
+    if (relationProperties.length === 0) return pairs;
+
+    const relationViews = getEntityChildViews(collection)
+        .filter(view => view.source.kind === "relation");
+    if (relationViews.length === 0) return pairs;
+
+    const resolvedRelations = resolveCollectionRelations(collection);
+    const identityOf = (relationKey: string): string =>
+        resolvedRelations[relationKey]?.relationName ?? relationKey;
+
+    const declaringPropertyByIdentity = new Map<string, string>();
+    for (const [propertyKey, property] of relationProperties) {
+        const relation = (property as RelationProperty).resolvedRelation ?? resolvedRelations[propertyKey];
+        // A to-one relation is a foreign key the author edits, never a tab. No
+        // view will match it — the views here are many-relations only — but
+        // reading the cardinality says so where someone is looking.
+        if (relation?.cardinality !== "many") continue;
+        const identity = relation.relationName ?? propertyKey;
+        if (!declaringPropertyByIdentity.has(identity)) declaringPropertyByIdentity.set(identity, propertyKey);
+    }
+
+    for (const view of relationViews) {
+        const propertyKey = declaringPropertyByIdentity.get(
+            identityOf((view.source as { relationKey: string }).relationKey));
+        if (propertyKey) pairs.set(view.key, propertyKey);
+    }
+
+    return pairs;
+}
+
+/**
+ * The property keys of `collection` whose relation is already one of its tabs.
+ *
+ * What a form asks: the tab is the treatment for a list of child rows, so the
+ * picker beside it is the redundant half. See
+ * {@link getChildViewDeclaringProperties}.
+ */
+export function getChildViewRelationPropertyKeys<M extends Record<string, unknown> = Record<string, unknown>>(
+    collection: CollectionConfig<M>
+): Set<string> {
+    return new Set(getChildViewDeclaringProperties(collection).values());
+}
+
 /**
  * The child views of `collection` as bare collections.
  *