@palbase/backend 24.3.0 → 25.0.0

package/dist/index.cjs

@@ -42,6 +42,12 @@ __export(src_exports, {
   NotFound: () => NotFound,
   Notifications: () => Notifications,
   On: () => On,
+  OnAuthorize: () => OnAuthorize,
+  OnEmpty: () => OnEmpty,
+  OnFirst: () => OnFirst,
+  OnJoin: () => OnJoin,
+  OnLeave: () => OnLeave,
+  OnMessage: () => OnMessage,
   OptionalUser: () => OptionalUser,
   PALBASE_EXTENSIONS: () => PALBASE_EXTENSIONS,
   PalError: () => PalError,
@@ -56,11 +62,13 @@ __export(src_exports, {
   Realtime: () => Realtime,
   Req: () => Req,
   RequestId: () => RequestId,
+  Room: () => Room,
   Secrets: () => Secrets,
   Signal: () => Signal,
   Sse: () => Sse,
   SseOut: () => SseOut,
   Storage: () => Storage,
+  TABLE_META: () => TABLE_META,
   TooManyRequests: () => TooManyRequests,
   TraceId: () => TraceId,
   TxPlanError: () => TxPlanError,
@@ -89,6 +97,7 @@ __export(src_exports, {
   defineError: () => defineError,
   defineMiddleware: () => defineMiddleware,
   defineSchema: () => defineSchema,
+  defineTable: () => defineTable,
   enumType: () => enumType,
   getErrorRegistry: () => getErrorRegistry,
   getHookConfig: () => getHookConfig,
@@ -97,6 +106,7 @@ __export(src_exports, {
   getRoutes: () => getRoutes,
   getWebhookConfig: () => getWebhookConfig,
   inc: () => inc,
+  installationRef: () => installationRef,
   integer: () => integer,
   isPalbaseExtension: () => isPalbaseExtension,
   jsonb: () => jsonb,
@@ -109,6 +119,7 @@ __export(src_exports, {
   onShutdown: () => onShutdown,
   onStart: () => onStart,
   openai: () => openai,
+  ownedByUser: () => ownedByUser,
   ownerOnly: () => ownerOnly,
   policy: () => policy,
   publicChannel: () => publicChannel,
@@ -118,6 +129,7 @@ __export(src_exports, {
   text: () => text,
   timestamp: () => timestamp,
   toSchemaJSON: () => toSchemaJSON,
+  userRef: () => userRef,
   uuid: () => uuid,
   vector: () => vector,
   z: () => import_zod2.z
@@ -639,13 +651,13 @@ function makeServiceProxy(key) {
   };
   return new Proxy({}, handler);
 }
-function makeTablesAccessor(ops) {
-  const tablesProxy = new Proxy(
+function makeTableProxy(ops, prefix) {
+  return new Proxy(
     {},
     {
       get(_t, prop) {
         if (typeof prop !== "string") return void 0;
-        const name = prop;
+        const name = `${prefix}${prop}`;
         return {
           insert: (data) => ops().insert(name, data),
           update: (id, data) => ops().update(name, id, data),
@@ -662,7 +674,12 @@ function makeTablesAccessor(ops) {
       }
     }
   );
-  return tablesProxy;
+}
+function makeTablesAccessor(ops) {
+  return makeTableProxy(ops, "");
+}
+function makeSchemaAccessor(ops, schema) {
+  return { tables: makeTableProxy(ops, `${String(schema)}.`) };
 }
 var rawDatabase = makeServiceProxy("Database");
 function makeTypedSurface(raw2) {
@@ -689,6 +706,7 @@ function makeTypedSurface(raw2) {
     // as one on the request's, and each is bound to its own connection.
     attempt: (fn) => raw2.attempt(fn),
     tables: makeTablesAccessor(() => reco),
+    schema: (name) => makeSchemaAccessor(() => reco, name),
     transaction(fn) {
       const builder = new TxPlanBuilder();
       return runTxPlan(raw2, makeTxTablesAccessor(builder), builder, fn);
@@ -1669,198 +1687,6 @@ function buildModuleClients(cfg) {
   };
 }
 
-// src/db/policy.ts
-function quote(name) {
-  return `"${name.replace(/"/g, '""')}"`;
-}
-var PolicyBuilder = class {
-  _def;
-  constructor(name) {
-    this._def = {
-      name,
-      command: "all",
-      roles: ["authenticated"],
-      using: null,
-      withCheck: null,
-      permissive: true
-    };
-  }
-  /** Restrict the policy to a single SQL command (default `"all"`). */
-  for(command) {
-    this._def.command = command;
-    return this;
-  }
-  /**
-   * Set the DB roles the policy applies to (the `TO` clause), replacing any
-   * previously-set roles. Call with no arguments to target PUBLIC (all roles).
-   *
-   * @example
-   * policy("p").to("authenticated")
-   * policy("p").to("authenticated", "service_role")
-   * policy("p").to() // PUBLIC
-   */
-  to(...roles) {
-    this._def.roles = roles;
-    return this;
-  }
-  /** Set the `USING (...)` row-visibility expression (raw SQL). */
-  using(sqlExpr) {
-    this._def.using = sqlExpr;
-    return this;
-  }
-  /**
-   * "Rows of THIS table whose owner the caller is a member of" — the membership
-   * pattern, written so it cannot recurse.
-   *
-   * THE TRAP IT EXISTS FOR. Written by hand, membership policies point at each
-   * other: `channels` is visible to members, so its policy reads
-   * `channel_members`; `channel_members` is visible to members, so its policy
-   * reads `channels`. Postgres refuses the pair at query time with `infinite
-   * recursion detected in policy for relation ...`, and the error names the
-   * relation but not the cycle. The way out is asymmetry — the MEMBERSHIP table
-   * is protected by `user_id = auth.uid()` and nothing else, and every other
-   * table subqueries INTO it. That shape was in the platform's own schema and
-   * written down nowhere; a customer recovered it by reading that schema.
-   *
-   * `(select auth.uid())` rather than a bare call: the scalar subquery is
-   * evaluated ONCE per statement instead of per row.
-   *
-   * @example
-   * // channels: visible to members. The membership table gets the simple one.
-   * policy("member_read").for("select").to("authenticated")
-   *   .memberOf("channel_members", "channel_id")
-   * // → id IN (SELECT "channel_id" FROM "channel_members"
-   * //          WHERE "user_id" = (select auth.uid()))
-   */
-  memberOf(membershipTable, foreignKey, options = {}) {
-    if (this._def.using !== null) {
-      throw new Error(
-        `policy(${this._def.name}).memberOf(): this policy already has a using() expression. Write one or the other \u2014 memberOf IS the using expression.`
-      );
-    }
-    const column = options.column ?? "id";
-    const userColumn = options.userColumn ?? "user_id";
-    this._def.using = `${quote(column)} IN (SELECT ${quote(foreignKey)} FROM ${quote(membershipTable)} WHERE ${quote(userColumn)} = (select auth.uid()))`;
-    return this;
-  }
-  /** Set the `WITH CHECK (...)` write-validation expression (raw SQL). */
-  withCheck(sqlExpr) {
-    this._def.withCheck = sqlExpr;
-    return this;
-  }
-  /** Set the policy mode: `"permissive"` (default, OR-combined) or
-   * `"restrictive"` (AND-combined). */
-  as(mode) {
-    this._def.permissive = mode === "permissive";
-    return this;
-  }
-};
-function policy(name) {
-  return new PolicyBuilder(name);
-}
-
-// src/db/schema.ts
-function toPolicyDef(p) {
-  return p instanceof PolicyBuilder ? p._def : p;
-}
-function defineSchema(input) {
-  const tables = {};
-  for (const name of Object.keys(input.tables)) {
-    const table = input.tables[name];
-    if (table === void 0) continue;
-    const policies = (table.policies ?? []).map(toPolicyDef);
-    const rls = policies.length > 0 || table.rls !== false;
-    const tableDef = {
-      name,
-      columns: table.columns,
-      rls,
-      policies
-    };
-    if (table.primaryKey !== void 0) tableDef.primaryKey = table.primaryKey;
-    if (table.unique !== void 0) tableDef.unique = table.unique;
-    if (table.raw !== void 0 && table.raw.length > 0) tableDef.raw = table.raw.slice();
-    if (table.checks !== void 0 && table.checks.length > 0) tableDef.checks = table.checks.slice();
-    if (table.indexes !== void 0 && table.indexes.length > 0) tableDef.indexes = table.indexes.slice();
-    if (table.search !== void 0) {
-      const s = table.search;
-      if (s.from !== void 0) {
-        if (s.vector !== void 0) {
-          throw new Error(
-            `table ${String(name)}: search beyan\u0131nda tek bi\xE7im kullan\u0131n \u2014 'from' (yeni) ile 'vector' (eski) birlikte olamaz`
-          );
-        }
-        if (s.from.length === 0) {
-          throw new Error(`table ${String(name)}: search.from bo\u015F olamaz`);
-        }
-        if (s.model === void 0) {
-          throw new Error(
-            `table ${String(name)}: search.from model'siz anlams\u0131z \u2014 auto-embed i\xE7in model verin (BYO i\xE7in eski 'vector' bi\xE7imini kullan\u0131n)`
-          );
-        }
-        if (Array.isArray(s.text) && s.text.length === 0) {
-          throw new Error(`table ${String(name)}: search.text bo\u015F dizi olamaz \u2014 FTS istemiyorsan text: false yaz\u0131n`);
-        }
-      } else {
-        if (typeof s.text === "boolean") {
-          throw new Error(`table ${String(name)}: text:${String(s.text)} yaln\u0131z yeni bi\xE7imde ('from' ile) ge\xE7erli`);
-        }
-        if (s.text === void 0 && s.vector === void 0) {
-          throw new Error(
-            `table ${String(name)}: search beyan\u0131 bo\u015F \u2014 en az bir kol (text ya da vector) verin, yoksa alan\u0131 hi\xE7 yazmay\u0131n`
-          );
-        }
-        if (s.text !== void 0 && s.text.length === 0) {
-          throw new Error(`table ${String(name)}: search.text bo\u015F olamaz \u2014 FTS kolu istemiyorsan alan\u0131 hi\xE7 yazma`);
-        }
-        const legs = s.vector === void 0 ? [] : Array.isArray(s.vector) ? s.vector : [s.vector];
-        for (const leg of legs) {
-          if (leg.model !== void 0 && (leg.from === void 0 || leg.from.length === 0)) {
-            throw new Error(`table ${String(name)}: search.vector.model beyan edildi ama 'from' yok \u2014 embed kayna\u011F\u0131 kolonlar zorunlu (C-2)`);
-          }
-          if (leg.model === void 0 && leg.from !== void 0) {
-            throw new Error(`table ${String(name)}: search.vector.from model'siz anlams\u0131z \u2014 auto-embed i\xE7in model verin`);
-          }
-        }
-      }
-      tableDef.search = s;
-    }
-    if (table.memory !== void 0) {
-      if (table.memory.from.length === 0) {
-        throw new Error(`table ${String(name)}: memory.from bo\u015F olamaz`);
-      }
-      tableDef.memory = table.memory;
-    }
-    tables[name] = tableDef;
-  }
-  for (const [name, def] of Object.entries(tables)) {
-    const m = def.memory;
-    if (m === void 0) continue;
-    const target = Object.values(tables).find((t) => t.name === m.into);
-    if (target === void 0) {
-      throw new Error(`table ${name}: memory.into "${m.into}" \u015Femada declared de\u011Fil`);
-    }
-    const subject = m.subject ?? "owner";
-    if (!(subject in def.columns)) {
-      throw new Error(`table ${name}: memory.subject "${subject}" kolonu kaynak tabloda yok`);
-    }
-    if (!(subject in target.columns)) {
-      throw new Error(`table ${name}: memory.subject "${subject}" kolonu hedef "${m.into}" tablosunda yok`);
-    }
-    const factCol = target.columns["fact"];
-    const factDef = factCol !== void 0 && "_def" in factCol ? factCol._def : factCol;
-    if (factDef === void 0 || factDef.type !== "text") {
-      throw new Error(`table ${name}: memory.into "${m.into}" tablosunda "fact" (text) kolonu zorunlu`);
-    }
-    for (const c of m.from) {
-      if (!(c in def.columns)) {
-        throw new Error(`table ${name}: memory.from kolonu "${c}" kaynak tabloda yok`);
-      }
-    }
-  }
-  const extensions = [...new Set(input.extensions ?? [])];
-  return { tables, extensions };
-}
-
 // src/db/schema-json.ts
 function defOf(column) {
   return "_def" in column ? column._def : column;
@@ -1969,13 +1795,14 @@ function memoryToJSON(m) {
     extract: { provider: m.extract.provider, model: m.extract.model }
   };
 }
-function tableToJSON(table) {
+function tableToJSON(table, schemaName) {
   const columns = {};
   for (const [name, column] of Object.entries(table.columns)) {
     columns[name] = columnToJSON(column);
   }
   const out = {
     name: table.name,
+    schema: schemaName,
     columns,
     // Read, not re-derived. `defineSchema` already resolves the fail-closed
     // default (RLS on unless the author wrote `rls: false`, and forced on by any
@@ -2014,13 +1841,296 @@ function tableToJSON(table) {
   }
   return out;
 }
-function toSchemaJSON(schema) {
+function qualifiedTableKey(schemaName, tableName) {
+  return schemaName === "public" ? tableName : `${schemaName}.${tableName}`;
+}
+function toSchemaJSON(schemas) {
   const tables = {};
-  for (const table of Object.values(schema.tables)) {
-    const json = tableToJSON(table);
-    tables[json.name] = json;
+  const extensions = [];
+  const meta = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const schema of schemas) {
+    if (seen.has(schema.name)) {
+      throw new Error(`two schemas declare the name "${schema.name}" \u2014 schema names must be unique`);
+    }
+    seen.add(schema.name);
+    for (const table of Object.values(schema.tables)) {
+      const json = tableToJSON(table, schema.name);
+      tables[qualifiedTableKey(schema.name, json.name)] = json;
+    }
+    extensions.push(...schema.extensions ?? []);
+    meta.push({ name: schema.name, exposed: schema.exposed });
   }
-  return { tables, extensions: [...new Set(schema.extensions ?? [])] };
+  return { tables, extensions: [...new Set(extensions)], schemas: meta };
+}
+
+// src/db/policy.ts
+function quote(name) {
+  return `"${name.replace(/"/g, '""')}"`;
+}
+var PolicyBuilder = class {
+  _def;
+  constructor(name) {
+    this._def = {
+      name,
+      command: "all",
+      roles: ["authenticated"],
+      using: null,
+      withCheck: null,
+      permissive: true
+    };
+  }
+  /** Restrict the policy to a single SQL command (default `"all"`). */
+  for(command) {
+    this._def.command = command;
+    return this;
+  }
+  /**
+   * Set the DB roles the policy applies to (the `TO` clause), replacing any
+   * previously-set roles. Call with no arguments to target PUBLIC (all roles).
+   *
+   * @example
+   * policy("p").to("authenticated")
+   * policy("p").to("authenticated", "service_role")
+   * policy("p").to() // PUBLIC
+   */
+  to(...roles) {
+    this._def.roles = roles;
+    return this;
+  }
+  /** Set the `USING (...)` row-visibility expression (raw SQL). */
+  using(sqlExpr) {
+    this._def.using = sqlExpr;
+    return this;
+  }
+  /**
+   * "Rows of THIS table whose owner the caller is a member of" — the membership
+   * pattern, written so it cannot recurse.
+   *
+   * THE TRAP IT EXISTS FOR. Written by hand, membership policies point at each
+   * other: `channels` is visible to members, so its policy reads
+   * `channel_members`; `channel_members` is visible to members, so its policy
+   * reads `channels`. Postgres refuses the pair at query time with `infinite
+   * recursion detected in policy for relation ...`, and the error names the
+   * relation but not the cycle. The way out is asymmetry — the MEMBERSHIP table
+   * is protected by `user_id = auth.uid()` and nothing else, and every other
+   * table subqueries INTO it. That shape was in the platform's own schema and
+   * written down nowhere; a customer recovered it by reading that schema.
+   *
+   * `(select auth.uid())` rather than a bare call: the scalar subquery is
+   * evaluated ONCE per statement instead of per row.
+   *
+   * @example
+   * // channels: visible to members. The membership table gets the simple one.
+   * policy("member_read").for("select").to("authenticated")
+   *   .memberOf("channel_members", "channel_id")
+   * // → id IN (SELECT "channel_id" FROM "channel_members"
+   * //          WHERE "user_id" = (select auth.uid()))
+   */
+  memberOf(membershipTable, foreignKey, options = {}) {
+    if (this._def.using !== null) {
+      throw new Error(
+        `policy(${this._def.name}).memberOf(): this policy already has a using() expression. Write one or the other \u2014 memberOf IS the using expression.`
+      );
+    }
+    const column = options.column ?? "id";
+    const userColumn = options.userColumn ?? "user_id";
+    this._def.using = `${quote(column)} IN (SELECT ${quote(foreignKey)} FROM ${quote(membershipTable)} WHERE ${quote(userColumn)} = (select auth.uid()))`;
+    return this;
+  }
+  /** Set the `WITH CHECK (...)` write-validation expression (raw SQL). */
+  withCheck(sqlExpr) {
+    this._def.withCheck = sqlExpr;
+    return this;
+  }
+  /** Set the policy mode: `"permissive"` (default, OR-combined) or
+   * `"restrictive"` (AND-combined). */
+  as(mode) {
+    this._def.permissive = mode === "permissive";
+    return this;
+  }
+};
+function policy(name) {
+  return new PolicyBuilder(name);
+}
+
+// src/db/schema.ts
+function toPolicyDef(p) {
+  return p instanceof PolicyBuilder ? p._def : p;
+}
+var TABLE_META = /* @__PURE__ */ Symbol.for("palbase.table.meta");
+function defineTable(name, input) {
+  if (name.trim() === "") {
+    throw new Error("defineTable(name, \u2026): name must not be empty");
+  }
+  const policies = (input.policies ?? []).map(toPolicyDef);
+  const rls = policies.length > 0 || input.rls !== false;
+  const def = {
+    name,
+    columns: input.columns,
+    rls,
+    policies
+  };
+  if (input.primaryKey !== void 0) def.primaryKey = input.primaryKey;
+  if (input.unique !== void 0) def.unique = input.unique;
+  if (input.raw !== void 0 && input.raw.length > 0) def.raw = input.raw.slice();
+  if (input.checks !== void 0 && input.checks.length > 0) def.checks = input.checks.slice();
+  if (input.indexes !== void 0 && input.indexes.length > 0) def.indexes = input.indexes.slice();
+  if (input.search !== void 0) {
+    const s = input.search;
+    if (s.from !== void 0) {
+      if (s.vector !== void 0) {
+        throw new Error(
+          `table ${name}: search beyan\u0131nda tek bi\xE7im kullan\u0131n \u2014 'from' (yeni) ile 'vector' (eski) birlikte olamaz`
+        );
+      }
+      if (s.from.length === 0) {
+        throw new Error(`table ${name}: search.from bo\u015F olamaz`);
+      }
+      if (s.model === void 0) {
+        throw new Error(
+          `table ${name}: search.from model'siz anlams\u0131z \u2014 auto-embed i\xE7in model verin (BYO i\xE7in eski 'vector' bi\xE7imini kullan\u0131n)`
+        );
+      }
+      if (Array.isArray(s.text) && s.text.length === 0) {
+        throw new Error(`table ${name}: search.text bo\u015F dizi olamaz \u2014 FTS istemiyorsan text: false yaz\u0131n`);
+      }
+    } else {
+      if (typeof s.text === "boolean") {
+        throw new Error(`table ${name}: text:${String(s.text)} yaln\u0131z yeni bi\xE7imde ('from' ile) ge\xE7erli`);
+      }
+      if (s.text === void 0 && s.vector === void 0) {
+        throw new Error(
+          `table ${name}: search beyan\u0131 bo\u015F \u2014 en az bir kol (text ya da vector) verin, yoksa alan\u0131 hi\xE7 yazmay\u0131n`
+        );
+      }
+      if (s.text !== void 0 && s.text.length === 0) {
+        throw new Error(`table ${name}: search.text bo\u015F olamaz \u2014 FTS kolu istemiyorsan alan\u0131 hi\xE7 yazma`);
+      }
+      const legs = s.vector === void 0 ? [] : Array.isArray(s.vector) ? s.vector : [s.vector];
+      for (const leg of legs) {
+        if (leg.model !== void 0 && (leg.from === void 0 || leg.from.length === 0)) {
+          throw new Error(`table ${name}: search.vector.model beyan edildi ama 'from' yok \u2014 embed kayna\u011F\u0131 kolonlar zorunlu (C-2)`);
+        }
+        if (leg.model === void 0 && leg.from !== void 0) {
+          throw new Error(`table ${name}: search.vector.from model'siz anlams\u0131z \u2014 auto-embed i\xE7in model verin`);
+        }
+      }
+    }
+    def.search = s;
+  }
+  if (input.memory !== void 0) {
+    if (input.memory.from.length === 0) {
+      throw new Error(`table ${name}: memory.from bo\u015F olamaz`);
+    }
+    def.memory = input.memory;
+  }
+  for (const b of Object.values(input.columns)) {
+    b._def.ownerTable = def;
+  }
+  const handle = { ...input.columns };
+  Object.defineProperty(handle, TABLE_META, { value: def, enumerable: false });
+  return handle;
+}
+var declaringSchemaOf = /* @__PURE__ */ new WeakMap();
+function resolveReferences(tables, schemaName) {
+  for (const table of Object.values(tables)) {
+    for (const [colName, builder] of Object.entries(table.columns)) {
+      const def = builder._def;
+      if (def.selfRefColumn !== void 0) {
+        if (!(def.selfRefColumn in table.columns)) {
+          throw new Error(
+            `table "${table.name}" column "${colName}": selfReferences("${def.selfRefColumn}") \u2014 no such column on this table`
+          );
+        }
+        def.references = {
+          table: qualifiedTableKey(schemaName, table.name),
+          column: def.selfRefColumn
+        };
+        continue;
+      }
+      if (def.referencesThunk === void 0) continue;
+      const target = def.referencesThunk();
+      const owner = target?._def?.ownerTable;
+      if (owner === void 0) {
+        throw new Error(
+          `table "${table.name}" column "${colName}": references(() => \u2026) must point at a column of a table declared with defineTable(...)`
+        );
+      }
+      const targetColumn = Object.entries(owner.columns).find(
+        ([, b]) => b._def === target._def
+      )?.[0];
+      if (targetColumn === void 0) {
+        throw new Error(
+          `table "${table.name}" column "${colName}": the referenced column was not found on table "${owner.name}"`
+        );
+      }
+      const targetSchema = declaringSchemaOf.get(owner);
+      if (targetSchema === void 0) {
+        throw new Error(
+          `table "${table.name}" column "${colName}": references(() => \u2026) points at table "${owner.name}", which no defineSchema(...) has claimed yet \u2014 a foreign key cannot be written without its target's schema. Declare that table's schema first (one file per schema: db/public.ts, db/billing.ts \u2026, imported by this one).`
+        );
+      }
+      def.references = {
+        table: qualifiedTableKey(targetSchema, owner.name),
+        column: targetColumn
+      };
+    }
+  }
+}
+function defineSchema(name, input) {
+  if (typeof name !== "string") {
+    throw new Error(
+      `defineSchema(...) takes the schema NAME first: defineSchema("public", { tables: [todos, lists] }). The one-argument form defineSchema({ tables: { \u2026 } }) is gone \u2014 a schema that does not say its own name cannot be told apart from another schema's table of the same name, which is what a cross-schema foreign key has to do. Migrate db/public.ts (one file per schema: db/public.ts, db/billing.ts \u2026): name the schema, and lift each table key onto the table itself with defineTable("todos", { columns: { \u2026 } }), then list the tables in the array.`
+    );
+  }
+  if (name.trim() === "") {
+    throw new Error("defineSchema(name, \u2026): name must not be empty");
+  }
+  const tables = {};
+  for (const handle of input.tables) {
+    const table = handle[TABLE_META];
+    if (tables[table.name] !== void 0) {
+      throw new Error(
+        `defineSchema("${name}"): two tables declare the name "${table.name}" \u2014 table names must be unique within a schema`
+      );
+    }
+    tables[table.name] = table;
+    declaringSchemaOf.set(table, name);
+  }
+  resolveReferences(tables, name);
+  for (const [name2, def] of Object.entries(tables)) {
+    const m = def.memory;
+    if (m === void 0) continue;
+    const target = Object.values(tables).find((t) => t.name === m.into);
+    if (target === void 0) {
+      throw new Error(`table ${name2}: memory.into "${m.into}" \u015Femada declared de\u011Fil`);
+    }
+    const subject = m.subject ?? "owner";
+    if (!(subject in def.columns)) {
+      throw new Error(`table ${name2}: memory.subject "${subject}" kolonu kaynak tabloda yok`);
+    }
+    if (!(subject in target.columns)) {
+      throw new Error(`table ${name2}: memory.subject "${subject}" kolonu hedef "${m.into}" tablosunda yok`);
+    }
+    const factCol = target.columns["fact"];
+    const factDef = factCol !== void 0 && "_def" in factCol ? factCol._def : factCol;
+    if (factDef === void 0 || factDef.type !== "text") {
+      throw new Error(`table ${name2}: memory.into "${m.into}" tablosunda "fact" (text) kolonu zorunlu`);
+    }
+    for (const c of m.from) {
+      if (!(c in def.columns)) {
+        throw new Error(`table ${name2}: memory.from kolonu "${c}" kaynak tabloda yok`);
+      }
+    }
+  }
+  const extensions = [...new Set(input.extensions ?? [])];
+  return {
+    name,
+    tables,
+    extensions,
+    exposed: input.exposed ?? name === "public"
+  };
 }
 
 // src/channels.ts
@@ -2222,59 +2332,46 @@ var ColumnBuilder = class _ColumnBuilder {
       ignored: true
     });
   }
-  references(table, column) {
-    refuseOnVector(this._def, "references");
-    this._def.references = { table, column };
-    return new _ColumnBuilder(this._def.type, this._def);
-  }
   /**
-   * Add a real DB-level foreign key to the built-in auth users
-   * (`REFERENCES auth.users(id)`), so a column like `user_id` gets true
-   * database cascade/integrity instead of app-layer-only. Sugar for
-   * `.references("auth.users", "id")`.
+   * Foreign key onto another table's column.
    *
-   * `auth.users` lives in the SAME tenant database (palauth-owned), so this is
-   * a genuine cross-schema integrity constraint scoped to THIS tenant's users.
-   * The referenced `auth.users.id` is `text` (palauth ids are `usr_<uuid>`), so
-   * the referencing column must be `text()` too.
+   * The target is a THUNK, not a direct reference. In a cycle (`x → y`, `y → x`)
+   * the second table does not exist yet when the first is built; a direct
+   * reference makes TypeScript chase its own tail (TS7022 — measured, and making
+   * the return type independent of the target does NOT help). The thunk is
+   * invoked in `defineSchema`, where every binding exists and every table
+   * already knows its name.
    *
-   * ON DELETE is REQUIRED here and may only be `cascade` or `set null`: an
-   * account-erasure request must never be blocked by a lingering FK, so
-   * `restrict` / `no action` are not accepted (they don't type-check). Example:
-   * `text().notNull().referencesAuthUser("cascade")`, or
-   * `text().nullable().referencesAuthUser("set null")`. The server
-   * (validateAuthUserFK) enforces this — and the remaining rules the type can't
-   * express (referencing column is text, `set null` needs a nullable column) —
-   * as the real boundary; this signature is the compile-time DX mirror.
+   * In a cycle, ONE side needs an explicit return type:
+   * `references((): AnyColumn => y.id)`. One side is enough — measured.
+   * For a self-reference use `selfReferences(column)`: no thunk, no annotation.
    */
-  referencesAuthUser(onDelete) {
-    refuseOnVector(this._def, "referencesAuthUser");
-    this._def.references = { table: "auth.users", column: "id" };
-    this._def.onDeleteAction = onDelete;
+  references(target, opts) {
+    refuseOnVector(this._def, "references");
+    if (typeof target !== "function") {
+      throw new Error(
+        `references(...) takes a callback: write references(() => otherTable.column). The two-string form references("table", "column") is gone \u2014 a string cannot be type-checked and cannot point at a table that does not exist yet.`
+      );
+    }
+    this._def.referencesThunk = target;
+    if (opts?.as !== void 0) this._def.refAs = opts.as;
+    if (opts?.onDelete !== void 0) this._def.onDeleteAction = opts.onDelete;
     return new _ColumnBuilder(this._def.type, this._def);
   }
   /**
-   * Add a real DB-level foreign key to the canonical, server-minted installation
-   * anchor (`REFERENCES auth.installations(id)`) — the app-scoped verified-device
-   * root (`ins_...`). Sugar for `.references("auth.installations", "id")`.
-   *
-   * An installation is an APP INSTALL, not a user: this FK is NOT user ownership.
-   * A user-owned row STILL needs its own `.referencesAuthUser(...)` FK so account
-   * erasure removes it — an installation reference alone does not tie a row to a
-   * user's deletion. Use this only for install-scoped state (device prefs, push
-   * routing, …), alongside a separate auth-user FK where the row is user-owned.
+   * Foreign key onto THIS table (`parent_id → id`) — category trees, comment
+   * replies, org charts.
    *
-   * `auth.installations` lives in the SAME tenant DB (palauth-owned); its `id` is
-   * `text` (`ins_<uuid>`), so the referencing column must be `text()` too. ON
-   * DELETE is REQUIRED and may only be `cascade` or `set null` (same allowed set
-   * as an auth-user FK): an installation revoke / orphan cleanup must never be
-   * blocked by a lingering FK. The server (validateAuthAnchorFK) is the real
-   * boundary; this signature is the compile-time DX mirror.
+   * No thunk and no type annotation: the target table is the one being declared,
+   * so there is nothing to defer and nothing for TypeScript to chase in a circle.
+   * Drizzle forces an explicit `(): AnyPgColumn =>` here because its reference
+   * always goes through a callback; measured, we do not need one.
    */
-  referencesInstallation(onDelete) {
-    refuseOnVector(this._def, "referencesInstallation");
-    this._def.references = { table: "auth.installations", column: "id" };
-    this._def.onDeleteAction = onDelete;
+  selfReferences(column, opts) {
+    refuseOnVector(this._def, "selfReferences");
+    this._def.selfRefColumn = column;
+    if (opts?.as !== void 0) this._def.refAs = opts.as;
+    if (opts?.onDelete !== void 0) this._def.onDeleteAction = opts.onDelete;
     return new _ColumnBuilder(this._def.type, this._def);
   }
   /** Set the ON DELETE action for a foreign key reference. */
@@ -2349,6 +2446,28 @@ function vector(dimensions) {
   b._def.dimensions = dimensions;
   return b;
 }
+function ownedByUser() {
+  const b = new ColumnBuilder("text");
+  b._def.nullable = false;
+  b._def.references = { table: "auth.users", column: "id" };
+  b._def.onDeleteAction = "cascade";
+  b._def.owns = true;
+  return b;
+}
+function userRef(opts) {
+  const b = new ColumnBuilder("text");
+  b._def.references = { table: "auth.users", column: "id" };
+  b._def.onDeleteAction = opts.onDelete;
+  if (opts.as !== void 0) b._def.refAs = opts.as;
+  return b;
+}
+function installationRef(opts) {
+  const b = new ColumnBuilder("text");
+  b._def.references = { table: "auth.installations", column: "id" };
+  b._def.onDeleteAction = opts.onDelete;
+  if (opts.as !== void 0) b._def.refAs = opts.as;
+  return b;
+}
 
 // src/db/raw.ts
 function raw(name, up, opts) {
@@ -2459,50 +2578,73 @@ function rowType(def) {
 function optionalOnInsert(def) {
   return def.nullable === true || def.defaultRandom === true || def.defaultNow === true || def.defaultValue !== void 0;
 }
-var AUTH_USERS_TABLE = "auth.users";
-function ownerColumnOf(table) {
-  for (const [col, builder] of Object.entries(table.columns)) {
-    if (builder._def.references?.table === AUTH_USERS_TABLE) return col;
-  }
-  return null;
+function forwardName(column) {
+  return column.endsWith("_id") ? column.slice(0, -3) : column;
 }
-function buildChildEdges(schema) {
-  const edges = /* @__PURE__ */ new Map();
-  for (const name of Object.keys(schema.tables)) edges.set(name, []);
-  for (const childName of Object.keys(schema.tables)) {
-    const table = schema.tables[childName];
-    if (table === void 0) continue;
-    for (const [col, builder] of Object.entries(table.columns)) {
-      const ref = builder._def.references;
-      if (ref === void 0) continue;
-      if (ref.table === childName) continue;
-      const bucket = edges.get(ref.table);
-      if (bucket === void 0) continue;
-      if (bucket.some((e) => e.child === childName)) continue;
-      bucket.push({ child: childName, column: col });
-    }
-  }
-  return edges;
+function qualify(schemaName, tableName) {
+  return schemaName === "public" ? tableName : `${schemaName}.${tableName}`;
 }
-function pruneCycles(raw2) {
-  const pruned = /* @__PURE__ */ new Map();
-  for (const table of raw2.keys()) pruned.set(table, []);
-  const state = /* @__PURE__ */ new Map();
-  function visit(table) {
-    state.set(table, "visiting");
-    for (const edge of raw2.get(table) ?? []) {
-      if (state.get(edge.child) === "visiting") continue;
-      pruned.get(table)?.push(edge);
-      if (state.get(edge.child) === void 0) visit(edge.child);
+function buildRelations(schemas) {
+  const out = /* @__PURE__ */ new Map();
+  const keyOf = /* @__PURE__ */ new Map();
+  for (const schema of schemas) {
+    for (const t of Object.values(schema.tables)) {
+      const key = qualify(schema.name, t.name);
+      out.set(key, []);
+      keyOf.set(t.name, key);
     }
-    state.set(table, "done");
   }
-  for (const table of raw2.keys()) {
-    if (state.get(table) === void 0) visit(table);
+  for (const schema of schemas) {
+    for (const table of Object.values(schema.tables)) {
+      const childKey = qualify(schema.name, table.name);
+      const bucket = out.get(childKey);
+      if (bucket === void 0) continue;
+      const byTarget = /* @__PURE__ */ new Map();
+      for (const [col, builder] of Object.entries(table.columns)) {
+        const ref = builder._def.references;
+        if (ref === void 0) continue;
+        const list = byTarget.get(ref.table) ?? [];
+        list.push(col);
+        byTarget.set(ref.table, list);
+      }
+      for (const [target, cols] of byTarget) {
+        if (cols.length < 2) continue;
+        const unnamed = cols.filter((c) => {
+          const d = table.columns[c]?._def;
+          return d?.refAs === void 0 && d?.owns !== true;
+        });
+        if (unnamed.length > 0) {
+          throw new Error(
+            `table "${table.name}" declares ${cols.length} foreign keys onto "${target}" (${cols.join(", ")}) \u2014 name each one: references(() => \u2026, { as: "\u2026" })`
+          );
+        }
+      }
+      for (const [col, builder] of Object.entries(table.columns)) {
+        const def = builder._def;
+        if (def.references === void 0) continue;
+        const name = def.owns === true ? "owner" : def.refAs ?? forwardName(col);
+        if (bucket.some((r) => r.name === name)) {
+          throw new Error(
+            name === "owner" ? `table "${table.name}": two columns claim ownership of the row \u2014 a table has at most ONE ownedByUser(). If the other column only POINTS at a user, declare it userRef({ onDelete: \u2026 }) instead.` : `table "${table.name}": two relations resolve to the name "${name}" \u2014 give one an explicit { as: "\u2026" }`
+          );
+        }
+        const targetKey = keyOf.get(def.references.table) ?? def.references.table;
+        bucket.push({ name, to: targetKey, kind: "one", via: col });
+        const parent = out.get(targetKey);
+        if (parent === void 0 || targetKey === childKey) continue;
+        const reverse = def.refAs ?? table.name;
+        if (parent.some((r) => r.name === reverse)) {
+          throw new Error(
+            `table "${def.references.table}": two reverse relations resolve to the name "${reverse}" \u2014 give one an explicit { as: "\u2026" }`
+          );
+        }
+        parent.push({ name: reverse, to: childKey, kind: "many", via: col });
+      }
+    }
   }
-  return pruned;
+  return out;
 }
-function tableBlock(table, children, indent) {
+function tableBlock(table, relations, indent) {
   const cols = Object.entries(table.columns);
   const rowLines = cols.map(([col, builder]) => {
     return `${indent}    ${col}: ${rowType(builder._def)};`;
@@ -2512,8 +2654,9 @@ function tableBlock(table, children, indent) {
     const opt = optionalOnInsert(def) ? "?" : "";
     return `${indent}    ${col}${opt}: ${rowType(def)};`;
   });
-  const owner = ownerColumnOf(table);
-  const childEntries = children.map((e) => `${JSON.stringify(e.child)}: ${JSON.stringify(e.column)}`).join("; ");
+  const relEntries = relations.map(
+    (r) => `${r.name}: { to: ${JSON.stringify(r.to)}; kind: ${JSON.stringify(r.kind)}; via: ${JSON.stringify(r.via)} }`
+  ).join("; ");
   return [
     `${indent}${table.name}: {`,
     `${indent}  row: {`,
@@ -2522,8 +2665,7 @@ function tableBlock(table, children, indent) {
     `${indent}  insert: {`,
     ...insertLines,
     `${indent}  };`,
-    `${indent}  owner: ${owner === null ? "null" : JSON.stringify(owner)};`,
-    `${indent}  children: {${childEntries === "" ? "" : ` ${childEntries} `}};`,
+    `${indent}  relations: {${relEntries === "" ? "" : ` ${relEntries} `}};`,
     // searchable: vector kolonu YA DA search beyanı → EnvTypedTable'da search()
     // üyesini açan yapısal bayrak (FR-013). Yokken satır hiç üretilmez ki
     // mevcut şemaların d.ts'i bayt-aynı kalsın.
@@ -2531,22 +2673,37 @@ function tableBlock(table, children, indent) {
     `${indent}};`
   ].join("\n");
 }
-function makeEnvDts(schema) {
-  const tableNames = Object.keys(schema.tables);
-  const children = pruneCycles(buildChildEdges(schema));
-  const blocks = tableNames.map(
-    (name) => tableBlock(schema.tables[name], children.get(name) ?? [], "    ")
+function makeEnvDts(schemas) {
+  const relations = buildRelations(schemas);
+  const qualify2 = (schemaName, table) => schemaName === "public" ? table : `${schemaName}.${table}`;
+  const publicSchema = schemas.find((s) => s.name === "public");
+  const others = schemas.filter((s) => s.name !== "public");
+  const publicBlocks = Object.keys(publicSchema?.tables ?? {}).map(
+    (name) => tableBlock(publicSchema.tables[name], relations.get(name) ?? [], "    ")
   );
-  const body = blocks.length > 0 ? `
-${blocks.join("\n")}
+  const body = publicBlocks.length > 0 ? `
+${publicBlocks.join("\n")}
+  ` : "";
+  const schemaBlocks = others.map((schema) => {
+    const inner = Object.keys(schema.tables).map(
+      (name) => tableBlock(schema.tables[name], relations.get(qualify2(schema.name, name)) ?? [], "      ")
+    );
+    return `    ${schema.name}: {
+${inner.join("\n")}
+    };`;
+  });
+  const schemasBody = schemaBlocks.length > 0 ? `
+${schemaBlocks.join("\n")}
   ` : "";
   return `// AUTO-GENERATED by @palbase/backend \u2014 DO NOT EDIT.
-// Regenerated from db/schema.ts by \`palbase build\` and by every deploy.
+// Regenerated from db/*.ts by \`palbase build\` and by every deploy.
 // Augments the @palbase/backend/env \`Tables\` interface so \`Database.tables.*\`
-// is typed with no import and no generic.
+// is typed with no import and no generic. Schemas other than \`public\` land
+// under \`Schemas\`, reached with \`Database.schema("<name>").tables.*\`.
 
 declare module "@palbase/backend/env" {
   interface Tables {${body}}
+  interface Schemas {${schemasBody}}
 }
 
 export {};
@@ -2602,6 +2759,8 @@ export {};
 // src/decorators/registry.ts
 var ROUTES = /* @__PURE__ */ Symbol.for("palbase.backend.routes");
 var PARAM_BUFFER = /* @__PURE__ */ Symbol.for("palbase.backend.paramBuffer");
+var ROOM = /* @__PURE__ */ Symbol.for("palbase.backend.room");
+var ROOM_HOOKS = /* @__PURE__ */ Symbol.for("palbase.backend.roomHooks");
 var RETURN_BUFFER = /* @__PURE__ */ Symbol.for("palbase.backend.returnBuffer");
 var THROWS_BUFFER = /* @__PURE__ */ Symbol.for("palbase.backend.throwsBuffer");
 function carrierOf(target) {
@@ -2690,6 +2849,38 @@ function getRoutes(ctor) {
     ...r.throws !== void 0 ? { throws: r.throws.slice() } : {}
   }));
 }
+function ownRoomBuffer(carrier) {
+  if (!Object.prototype.hasOwnProperty.call(carrier, ROOM_HOOKS)) {
+    carrier[ROOM_HOOKS] = { hooks: {}, messages: {} };
+  }
+  return carrier[ROOM_HOOKS];
+}
+function recordRoomHook(target, hook, fnName) {
+  const buffer = ownRoomBuffer(carrierOf(target));
+  const existing = buffer.hooks[hook];
+  if (existing !== void 0 && existing !== fnName) {
+    const label = `On${hook.charAt(0).toUpperCase()}${hook.slice(1)}`;
+    throw new Error(
+      `@${label} is declared twice in one room (${existing} and ${fnName}). A room has one of each hook.`
+    );
+  }
+  buffer.hooks[hook] = fnName;
+}
+function recordRoomMessage(target, name, fnName, schema) {
+  const buffer = ownRoomBuffer(carrierOf(target));
+  const existing = buffer.messages[name];
+  if (existing !== void 0 && existing.fnName !== fnName) {
+    throw new Error(
+      `@OnMessage("${name}") is declared twice in one room (${existing.fnName} and ${fnName}).`
+    );
+  }
+  buffer.messages[name] = { fnName, schema };
+}
+function recordRoom(ctor, meta) {
+  const carrier = carrierOf(ctor);
+  const buffer = ownRoomBuffer(carrier);
+  carrier[ROOM] = { ...meta, hooks: buffer.hooks, messages: buffer.messages };
+}
 
 // src/decorators/controller.ts
 var CONTROLLER_META = /* @__PURE__ */ Symbol.for("palbase.backend.controllerMeta");
@@ -3002,6 +3193,56 @@ function Signal() {
   };
 }
 
+// src/decorators/room.ts
+var DEFAULT_GRACE_MS = 6e4;
+function assertPattern(pattern) {
+  if (pattern.includes("/")) {
+    throw new Error(
+      `@Room("${pattern}"): channel patterns are colon-separated, not slash-separated. Write "${pattern.replace(/\//g, ":")}" \u2014 a slash matches no live topic.`
+    );
+  }
+  const segments = pattern.split(":");
+  if (segments.some((s) => s === "")) {
+    throw new Error(`@Room("${pattern}"): empty segment \u2014 every segment must be non-empty.`);
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const s of segments) {
+    if (!s.startsWith("{") || !s.endsWith("}")) continue;
+    const name = s.slice(1, -1);
+    if (name === "") throw new Error(`@Room("${pattern}"): "{}" names no parameter.`);
+    if (seen.has(name)) {
+      throw new Error(`@Room("${pattern}"): parameter "{${name}}" appears twice.`);
+    }
+    seen.add(name);
+  }
+}
+function Room(pattern, options) {
+  return function(ctor) {
+    assertPattern(pattern);
+    recordRoom(ctor, {
+      pattern,
+      events: options.events,
+      graceMs: options.graceMs ?? DEFAULT_GRACE_MS
+    });
+    return ctor;
+  };
+}
+function hookDecorator(hook) {
+  return () => function(target, propertyKey) {
+    recordRoomHook(target, hook, String(propertyKey));
+  };
+}
+var OnAuthorize = hookDecorator("authorize");
+var OnFirst = hookDecorator("first");
+var OnJoin = hookDecorator("join");
+var OnLeave = hookDecorator("leave");
+var OnEmpty = hookDecorator("empty");
+function OnMessage(name, schema) {
+  return function(target, propertyKey) {
+    recordRoomMessage(target, name, String(propertyKey), schema);
+  };
+}
+
 // src/decorators/params.ts
 function makeParamDecorator(kind, extra) {
   return function(target, propertyKey, parameterIndex) {
@@ -3422,6 +3663,12 @@ var import_zod2 = require("zod");
   NotFound,
   Notifications,
   On,
+  OnAuthorize,
+  OnEmpty,
+  OnFirst,
+  OnJoin,
+  OnLeave,
+  OnMessage,
   OptionalUser,
   PALBASE_EXTENSIONS,
   PalError,
@@ -3436,11 +3683,13 @@ var import_zod2 = require("zod");
   Realtime,
   Req,
   RequestId,
+  Room,
   Secrets,
   Signal,
   Sse,
   SseOut,
   Storage,
+  TABLE_META,
   TooManyRequests,
   TraceId,
   TxPlanError,
@@ -3469,6 +3718,7 @@ var import_zod2 = require("zod");
   defineError,
   defineMiddleware,
   defineSchema,
+  defineTable,
   enumType,
   getErrorRegistry,
   getHookConfig,
@@ -3477,6 +3727,7 @@ var import_zod2 = require("zod");
   getRoutes,
   getWebhookConfig,
   inc,
+  installationRef,
   integer,
   isPalbaseExtension,
   jsonb,
@@ -3489,6 +3740,7 @@ var import_zod2 = require("zod");
   onShutdown,
   onStart,
   openai,
+  ownedByUser,
   ownerOnly,
   policy,
   publicChannel,
@@ -3498,6 +3750,7 @@ var import_zod2 = require("zod");
   text,
   timestamp,
   toSchemaJSON,
+  userRef,
   uuid,
   vector,
   z