@rebasepro/server-postgres 0.13.1-canary.gf57a27e → 0.14.0

package/dist/services/PersistService.d.ts

@@ -1,4 +1,5 @@
 import { RelationService } from "./RelationService";
+import { RelationWriteService } from "./RelationWriteService";
 import { FetchService } from "./FetchService";
 import { DrizzleClient } from "../interfaces";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
@@ -9,25 +10,15 @@ import { PostgresCollectionRegistry } from "../collections/PostgresCollectionReg
 export declare class PersistService {
     private db;
     private registry;
+    /** Reads: whether a row is under a parent, the key a link joins on. */
     private relationService;
+    /** Writes: junction membership, foreign-key stamping, links. */
+    private relationWrites;
     private fetchService;
     constructor(db: DrizzleClient, registry: PostgresCollectionRegistry);
     /**
-     * Explain a write that matched no rows.
-     *
-     * Row-level security filters UPDATE and DELETE through the policy's USING
-     * clause instead of raising: a denied write is reported by Postgres exactly
-     * like a successful one that happened to match nothing. Left unchecked, a
-     * caller cannot tell "denied" from "done" — the write returns 200/204 and
-     * the row is untouched.
-     *
-     * Re-reading the target over the *same* RLS-scoped handle separates the two
-     * cases. A visible row means the policy rejected the write (403); an
-     * invisible one means there is nothing there to write for this caller (404,
-     * matching what a GET would say). The re-read is bound by the caller's own
-     * policies, so it discloses nothing a plain read wouldn't.
-     *
-     * Only reached when zero rows matched, so the happy path pays nothing.
+     * Explain a row write that matched nothing — see {@link explainZeroRowWrite}
+     * for why a zero-row write cannot be reported as success.
      */
     private explainZeroRowWrite;
     /**
@@ -39,8 +30,14 @@ export declare class PersistService {
      */
     deleteAll(collectionPath: string, _databaseId?: string): Promise<void>;
     /**
-     * The column on the *target* table that records the parent, for a create
-     * under a nested one-to-many path.
+     * The field on the *target* row that records the parent, for a create under
+     * a nested one-to-many path.
+     *
+     * A **field**, not the column: the value is stamped into the caller's
+     * payload, which is keyed by wire names — `authorId`, never the `author_id`
+     * the relation names its link by. Stamping the column instead put a key on
+     * the payload that no property answers to, and `strictWrites` rejected the
+     * request the framework had just written to.
      *
      * Returns `undefined` when the link is not a column at all (a multi-hop
      * `joinPath`), so the caller writes the row without stamping anything.
@@ -66,6 +63,13 @@ export declare class PersistService {
      * Get the RelationService instance for external use
      */
     getRelationService(): RelationService;
+    /**
+     * The write half, for external use. Separate from
+     * {@link getRelationService} because they are separate objects now: reads
+     * answer questions, writes change rows, and the callers of one are not the
+     * callers of the other.
+     */
+    getRelationWriteService(): RelationWriteService;
     /**
      * Get the FetchService instance for external use
      */

package/dist/services/RelationService.d.ts

@@ -1,6 +1,5 @@
 import { DrizzleClient } from "../interfaces";
-import { CollectionConfig, FilterValues, ResolvedRelation, ResolvedManyToMany, ResolvedHasMany, ResolvedHasOne } from "@rebasepro/types";
-import { type ResolvedVia } from "@rebasepro/types";
+import { CollectionConfig, FilterValues, ResolvedRelation, ResolvedHasMany, ResolvedHasOne } from "@rebasepro/types";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
 import type { NestedPathHop } from "./nested-path";
 /**
@@ -78,7 +77,14 @@ export declare class RelationService {
      * nested path and would otherwise write the id and lose the row.
      */
     parentKeyValue(parentCollection: CollectionConfig, relation: ResolvedHasOne | ResolvedHasMany, parentId: string | number, db?: DrizzleClient): Promise<string | number | undefined>;
-    private resolveSourceKeys;
+    /**
+     * Shared with {@link RelationWriteService}: a write needs the same source
+     * key a read does, and resolving it twice is how the two would disagree.
+     */
+    resolveSourceKeys(parentCollection: CollectionConfig, relation: ResolvedHasOne | ResolvedHasMany, parentIds: (string | number)[], db?: DrizzleClient): Promise<{
+        keyByParentId: Map<string, string | number>;
+        parentIdByKey: Map<string, string | number>;
+    }>;
     /**
      * Fetch rows related to a parent row through a specific relation
      */
@@ -129,16 +135,6 @@ export declare class RelationService {
      * belonged to. Reads, updates and deletes now all gate on this.
      */
     isRelated(hop: NestedPathHop, targetId: string | number): Promise<boolean>;
-    /**
-     * Remove the junction row linking a parent to `targetId`, leaving the target
-     * row itself alone.
-     *
-     * This is what `DELETE authors/1/tags/5` has to mean for a many-to-many: the
-     * target is shared, so deleting the row would remove the tag from every other
-     * post that uses it. It used to do exactly that — resolve the path to the
-     * `tags` table and delete by primary key.
-     */
-    unlinkRelatedEntity(tx: DrizzleClient, hop: NestedPathHop, targetId: string | number): Promise<void>;
     /**
      * Batch fetch related rows for multiple parent rows to avoid N+1 queries
      */
@@ -149,48 +145,4 @@ export declare class RelationService {
      * Uses a single SQL query with IN clause to avoid N+1.
      */
     batchFetchRelatedEntitiesMany(parentCollectionPath: string, parentIds: (string | number)[], _relationKey: string, relation: ResolvedRelation): Promise<Map<string, RelatedRow<Record<string, unknown>>[]>>;
-    /**
-     * Update many-to-many and junction relations
-     */
-    updateRelationsUsingJoins<M extends Record<string, unknown>>(tx: DrizzleClient, collection: CollectionConfig, id: string | number, relationValues: Partial<M>): Promise<void>;
-    /**
-     * Update inverse relations (where FK is on the target table)
-     */
-    updateInverseRelations(tx: DrizzleClient, sourceCollection: CollectionConfig, sourceEntityId: string | number, inverseRelationUpdates: Array<{
-        relationKey: string;
-        relation: ResolvedRelation;
-        newValue: unknown;
-    }>): Promise<void>;
-    /**
-     * Handle inverse relations with joinPath
-     */
-    private updateInverseJoinPathRelation;
-    /**
-     * Handle many-to-many inverse relation updates using junction tables
-     */
-    private updateManyToManyInverseRelation;
-    /**
-     * Update one-to-one relations that use joinPath
-     */
-    updateJoinPathOneToOneRelations(tx: DrizzleClient, parentCollection: CollectionConfig, parentId: string | number, updates: Array<{
-        relationKey: string;
-        relation: ResolvedVia;
-        newTargetId: string | number | null;
-    }>): Promise<void>;
-    /**
-     * Resolve joinPath write mapping for one-to-one relations
-     */
-    resolveJoinPathWriteMapping(parentCollection: CollectionConfig, relation: ResolvedVia): {
-        targetFKColName: string;
-        parentSourceColName: string;
-    };
-    /**
-     * Handle junction table creation for many-to-many path-based saves
-     */
-    handleJunctionTableCreation(tx: DrizzleClient, newEntityId: string | number, junctionTableInfo: {
-        parentCollection: CollectionConfig;
-        parentId: string | number;
-        relation: ResolvedManyToMany;
-        relationKey: string;
-    }): Promise<void>;
 }

package/dist/services/RelationWriteService.d.ts

@@ -0,0 +1,82 @@
+import { CollectionConfig, ResolvedManyToMany, ResolvedRelation, ResolvedVia } from "@rebasepro/types";
+import { DrizzleClient } from "../interfaces";
+import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
+import type { NestedPathHop } from "./nested-path";
+/**
+ * Writing relations: junction membership, foreign-key stamping, and the links a
+ * nested path creates or removes.
+ *
+ * Split from {@link RelationService}, which now only reads. The two had grown
+ * into one 1700-line class doing two unrelated jobs, and sharing one habit —
+ * warning about a relation it could not resolve and carrying on, which surfaces
+ * as an empty list on the read side and as a successful save on the write side.
+ * Separating them is what made that visible as one class of defect rather than
+ * eighteen scattered log lines.
+ *
+ * The reads it still needs — the source key a link joins on — it asks
+ * {@link RelationService} for rather than reimplementing.
+ */
+export declare class RelationWriteService {
+    private db;
+    private registry;
+    private reads;
+    constructor(db: DrizzleClient, registry: PostgresCollectionRegistry);
+    /**
+     * Remove the junction row linking a parent to `targetId`, leaving the target
+     * row itself alone.
+     *
+     * This is what `DELETE authors/1/tags/5` has to mean for a many-to-many: the
+     * target is shared, so deleting the row would remove the tag from every other
+     * post that uses it. It used to do exactly that — resolve the path to the
+     * `tags` table and delete by primary key.
+     */
+    unlinkRelatedEntity(tx: DrizzleClient, hop: NestedPathHop, targetId: string | number): Promise<void>;
+    /** A collection's id, parsed to the type its primary key column holds. */
+    private parsedId;
+    /** The same, for the membership list a to-many write names. */
+    private parsedIds;
+    /**
+     * Update many-to-many and junction relations
+     */
+    updateRelationsUsingJoins<M extends Record<string, unknown>>(tx: DrizzleClient, collection: CollectionConfig, id: string | number, relationValues: Partial<M>): Promise<void>;
+    /**
+     * Update inverse relations (where FK is on the target table)
+     */
+    updateInverseRelations(tx: DrizzleClient, sourceCollection: CollectionConfig, sourceEntityId: string | number, inverseRelationUpdates: Array<{
+        relationKey: string;
+        relation: ResolvedRelation;
+        newValue: unknown;
+    }>): Promise<void>;
+    /**
+     * Handle inverse relations with joinPath
+     */
+    private updateInverseJoinPathRelation;
+    /**
+     * Handle many-to-many inverse relation updates using junction tables
+     */
+    private updateManyToManyInverseRelation;
+    /**
+     * Update one-to-one relations that use joinPath
+     */
+    updateJoinPathOneToOneRelations(tx: DrizzleClient, parentCollection: CollectionConfig, parentId: string | number, updates: Array<{
+        relationKey: string;
+        relation: ResolvedVia;
+        newTargetId: string | number | null;
+    }>): Promise<void>;
+    /**
+     * Resolve joinPath write mapping for one-to-one relations
+     */
+    resolveJoinPathWriteMapping(parentCollection: CollectionConfig, relation: ResolvedVia): {
+        targetFKColName: string;
+        parentSourceColName: string;
+    };
+    /**
+     * Handle junction table creation for many-to-many path-based saves
+     */
+    handleJunctionTableCreation(tx: DrizzleClient, newEntityId: string | number, junctionTableInfo: {
+        parentCollection: CollectionConfig;
+        parentId: string | number;
+        relation: ResolvedManyToMany;
+        relationKey: string;
+    }): Promise<void>;
+}

package/dist/services/collection-helpers.d.ts

@@ -1,6 +1,7 @@
 import { PgTable, AnyPgColumn } from "drizzle-orm/pg-core";
 import { CollectionConfig, ResolvedHasMany, ResolvedHasOne } from "@rebasepro/types";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
+import { ApiError } from "@rebasepro/server";
 export { buildCompositeId, parseIdValues, isAddressableId, COMPOSITE_ID_SEPARATOR } from "@rebasepro/common";
 export type { PrimaryKeyInfo } from "@rebasepro/common";
 import type { PrimaryKeyInfo } from "@rebasepro/common";
@@ -34,6 +35,47 @@ export declare function getColumnMeta(col: AnyPgColumn): DrizzleColumnMeta;
  */
 export declare function idCanAddressTable(id: string | number, table: PgTable, idInfoArray: PrimaryKeyInfo[]): boolean;
 export declare function getCollectionByPath(collectionPath: string, registry: PostgresCollectionRegistry): CollectionConfig;
+/**
+ * Reject a write naming something that is not a column of the table.
+ *
+ * Drizzle builds INSERT from `Object.entries(table[Symbol.Columns])` and UPDATE
+ * from `Object.keys(tableColumns)`, so a key the table does not carry is not
+ * rejected by anything — it is *left out of the statement*. The insert answers
+ * 201 having stored nothing under that name; the update, if the key was the
+ * only one, builds `update "posts" set  where …` and Postgres raises a syntax
+ * error (SQLSTATE 42601), which is neither class 22 nor 23 and so surfaces as a
+ * 500 for what is a caller's typo.
+ *
+ * That makes this the last honest place to check, and the only one every write
+ * passes through. `assertKnownWriteFields` in the REST layer checks the same
+ * thing against the *config* and is skipped on four paths — `strictWrites:
+ * false`, a collection declaring no properties, an auth adapter that owns the
+ * body's shape, and a nested route whose target cannot be walked — and it never
+ * sees an in-process `rebase.data` write at all.
+ *
+ * It also gives `strictWrites: false` a truthful implementation. The flag is
+ * documented for "a column that really does exist which the config never
+ * declared", and skipping the config check alone could not deliver that: the
+ * value was dropped a layer later regardless. Skipping the config check and
+ * keeping this one does exactly what the flag says — the column must exist,
+ * the property need not.
+ */
+export declare function assertWritableColumns(values: Record<string, unknown>, table: PgTable, collectionPath: string): void;
+/**
+ * A relation whose names do not resolve against the registered schema.
+ *
+ * Every one of these used to be a `logger.warn` followed by `continue`, so a
+ * save reported success for a relation it had not written and a read answered
+ * `[]` for one it could not resolve. `assertRelationsResolve` (validate-relations)
+ * fails boot on the same defects, which is where they belong — a server that
+ * refuses to start is recoverable in a minute. This is the second line, for the
+ * paths that assemble a registry by hand, and it exists so that "cannot resolve"
+ * is never again reported as "done".
+ *
+ * @param label  `<collection>.<relation>`
+ * @param detail what does not resolve, in terms of the schema
+ */
+export declare function relationMisconfigured(label: string, detail: string): ApiError;
 export declare function getTableForCollection(collection: CollectionConfig, registry: PostgresCollectionRegistry): PgTable<any>;
 /**
  * The key columns a collection's rows are addressed by.

package/dist/services/dataService.d.ts

@@ -52,6 +52,8 @@ export declare class DataService implements DataRepository {
      */
     searchRows<M extends Record<string, unknown>>(collectionPath: string, searchString: string, options?: {
         filter?: FilterValues<Extract<keyof M, string>>;
+        /** An `or(...)`/`and(...)` group, applied alongside `filter`. */
+        logical?: LogicalCondition;
         orderBy?: string;
         order?: "desc" | "asc";
         limit?: number;

package/dist/services/junction-writes.d.ts

@@ -0,0 +1,82 @@
+import { AnyPgColumn, PgTable } from "drizzle-orm/pg-core";
+import type { ResolvedVia } from "@rebasepro/types";
+import { DrizzleClient } from "../interfaces";
+import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
+/**
+ * Writing a many-to-many means writing rows in a junction table, and doing that
+ * needs three things: the table, the column naming the row being written from,
+ * and the column naming the far side.
+ *
+ * Those three used to be re-derived at each of the four call sites — twice for
+ * `through`, twice for `joinPath`, in the owning and the inverse direction —
+ * and the two `joinPath` derivations did not agree. The inverse one keyed off
+ * `step.table`; the owning one asked `getTableNamesFromColumns` which table a
+ * step's columns belonged to, and that answers `""` for an unqualified column
+ * name. So for `{ table: "posts_tags", on: { from: "id", to: "tag_id" } }` —
+ * the form the docs and every fixture use — no branch matched, both columns
+ * stayed null, and the write was skipped with a warning nobody reads. Writing
+ * a to-many `via` relation did nothing at all.
+ *
+ * Hence one binder, keyed on `step.table` (always present) and accepting the
+ * qualified `table.column` form where it is used.
+ */
+export interface JunctionBinding {
+    table: PgTable;
+    /** The junction column holding the id of the row being written from. */
+    parentColumn: AnyPgColumn;
+    /** The junction column holding the id of the row on the far side. */
+    targetColumn: AnyPgColumn;
+    /** `<collection>.<relation>`, for error messages. */
+    label: string;
+}
+/** The junction a `manyToMany` names outright. */
+export declare function bindThroughJunction(registry: PostgresCollectionRegistry, through: {
+    table: string;
+    sourceColumn: string;
+    targetColumn: string;
+}, label: string): JunctionBinding;
+/**
+ * The junction a `via` relation reaches through, from either end.
+ *
+ * A step is `{ table: T, on: { from, to } }` where `from` names a column on
+ * whatever the walk was standing on and `to` names one on `T`. That positional
+ * meaning is what makes the unqualified form work at all, so the walk carries
+ * the previous table rather than asking the column names where they live.
+ */
+export declare function bindJoinPathJunction(registry: PostgresCollectionRegistry, joinPath: ResolvedVia["joinPath"], parentTableName: string, targetTableName: string, label: string): JunctionBinding;
+/**
+ * Remove one link, leaving the row on the far side alone.
+ *
+ * This is what `DELETE authors/1/tags/5` has to mean for a many-to-many: the
+ * target is shared, so deleting the row would remove the tag from every other
+ * post that uses it.
+ */
+export declare function removeJunctionLink(tx: DrizzleClient, binding: JunctionBinding, parentId: unknown, targetId: unknown, subject: {
+    parent: string;
+    relation: string;
+}): Promise<void>;
+/**
+ * Make the junction say that `parentId` is linked to exactly `targetIds`, by
+ * diffing against what is linked now rather than replacing the set.
+ *
+ * A save of the parent used to delete every junction row for it and re-insert
+ * the ids the browser sent — a list the browser assembled from a read it did
+ * earlier. Three things followed, all data loss rather than display:
+ *
+ *  - **Lost update.** Two editors with post 7 open: A adds tag X and saves, B
+ *    saves any field from a form that predates it, and X is gone with nothing
+ *    reported to either of them.
+ *  - **A partially-read set is a partially-deleted set.** The read that fills
+ *    the form runs under RLS, so a user who may edit the parent but cannot see
+ *    some of the linked rows gets a shorter list — and writing it back deleted
+ *    the links they were never shown. The select that drives the diff runs in
+ *    this same transaction under the same policies, so a link the caller cannot
+ *    read is in neither list and survives the save.
+ *  - **Junction payload columns.** A junction carrying its own columns
+ *    (`position`, `role`, `created_at`) lost them on every save, because every
+ *    row was re-inserted with only the two keys. Untouched links are left alone.
+ *
+ * The insert is `ON CONFLICT DO NOTHING`, so two sessions adding the same link
+ * concurrently is a no-op rather than a unique violation.
+ */
+export declare function applyJunctionMembership(tx: DrizzleClient, binding: JunctionBinding, parentId: unknown, targetIds: unknown[]): Promise<void>;

package/dist/services/realtimeService.d.ts

@@ -14,6 +14,34 @@ export interface SubscriptionAuthContext {
     uid: string;
     roles: string[];
 }
+/** What a channel frame is asking to do. */
+export type ChannelAction = "join" | "broadcast" | "presence" | "history";
+/** Everything an authorizer is told about the frame it is asked to allow. */
+export interface ChannelAuthorizationRequest {
+    /** The channel the frame names, exactly as the client wrote it. */
+    channel: string;
+    action: ChannelAction;
+    /** The socket, not the principal — one user may hold several. */
+    clientId: string;
+    /** The socket's authenticated principal, or the anonymous one. */
+    user?: SubscriptionAuthContext;
+}
+/**
+ * The extension point for channel access rules.
+ *
+ * **This is deliberately not a product API yet.** The rule *language* — a
+ * config key, a per-pattern DSL, how it composes with `securityRules` — is an
+ * open design question (see `docs/channel-authorization.md`), and
+ * inventing one here would be inventing the answer. What exists is the single
+ * place every channel frame passes through, so that whatever shape the rules
+ * eventually take has exactly one seam to plug into and no arm of the switch
+ * can be forgotten.
+ *
+ * Returning `false` — or throwing — refuses the frame. It is consulted *after*
+ * the membership floor below, so an authorizer can only ever narrow access,
+ * never widen it.
+ */
+export type ChannelAuthorizer = (request: ChannelAuthorizationRequest) => boolean | Promise<boolean>;
 /**
  * The narrowing a collection subscription was created with, kept so that every
  * refetch answers the same query the initial fetch did.
@@ -46,6 +74,12 @@ type StoredCollectionRequest = {
 export declare class RealtimeService extends EventEmitter implements RealtimeProvider {
     private db;
     private registry;
+    /**
+     * Declares to the multi-engine router that channel frames can be handled
+     * here. Read by `createRoutedRealtimeService`, which otherwise would have to
+     * guess — and guessed "the default provider", whichever engine that is.
+     */
+    readonly supportsChannels = true;
     private clients;
     private channels;
     private presence;
@@ -92,6 +126,23 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      * so a hot channel logs the problem once rather than once per message.
      */
     private oversizedBroadcastWarned;
+    /**
+     * Optional narrowing on top of the membership floor — see
+     * {@link ChannelAuthorizer}. Unset by default, which leaves membership as
+     * the whole of the rule.
+     */
+    private channelAuthorizer?;
+    /**
+     * Whether a notification from another instance has ever arrived.
+     *
+     * The entity LISTEN handler sees a foreign `sid` on every cross-instance
+     * change, which is proof that this deployment runs more than one pod — the
+     * one fact needed to tell "the memory bus is fine here" from "broadcast and
+     * presence silently reach a fraction of your users".
+     */
+    private foreignInstanceSeen;
+    /** So the multi-pod memory-bus warning is emitted once, not once per join. */
+    private memoryBusWarned;
     private presenceInterval?;
     private static readonly PRESENCE_TIMEOUT_MS;
     /** How often stale roster rows from other instances are reaped. */
@@ -196,7 +247,39 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      */
     notifyUpdate(path: string, id: string, row: Record<string, unknown> | null, databaseId?: string, broadcast?: boolean, origin?: "app" | "cdc"): Promise<void>;
     /**
-     * Notify subscriptions for a specific path
+     * Notify subscriptions for a specific path.
+     *
+     * **A subscriber only ever receives rows re-read under its own scope.**
+     * `row` is used to decide *that* something changed, never to say *what* —
+     * every delivery below goes through a refetch that binds the subscription's
+     * own auth context.
+     *
+     * It used to be conditional. The CDC path already did the right thing: it
+     * discards the captured tuple and emits `{_rebase_invalidated: true}`, and
+     * that marker selected the refetch branch. But the marker is produced in
+     * exactly two places, and the *other* side of each branch here shipped the
+     * row it was handed straight to the socket. Two of the three entry paths
+     * took that side — every API mutation (`PostgresBackendDriver.save` passes
+     * the row it just wrote, read under the **writer's** scope) and the legacy
+     * cross-instance LISTEN handler (which re-reads on the owner connection,
+     * bypassing RLS altogether). Path matching was the only filter applied: the
+     * subscription's own `filter`/`logical` was never evaluated, and any
+     * `afterRead` redaction was the writer's rather than the reader's.
+     *
+     * A single-row subscription was the sharpest case. `subscribe_one` on a row
+     * RLS denies is accepted and answered `null`; the next update then pushed
+     * the full row with no later correction. The collection variant was merely
+     * papered over ~300 ms later by the debounced refetch — after the bytes had
+     * already reached the browser.
+     *
+     * The same defect was found and fixed on the Mongo driver in `065e2b615`
+     * (see `packages/server-mongo/test/realtime-authorization.test.ts`); this is
+     * the Postgres half, stated as one rule rather than three patched branches.
+     *
+     * The cost is the instant row-level patch that used to precede the refetch:
+     * cross-tab feedback now waits for the debounce. That is the price of not
+     * being able to know, without asking the database as this subscriber,
+     * whether this subscriber may see the row at all.
      */
     private notifyPathUpdate;
     /**
@@ -237,7 +320,6 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      * columns and no address. The SDK holds no collection config to derive one
      * from, so this is the only place the mapping can come from.
      */
-    private sendCollectionPatch;
     /** The key columns of the collection at `path`, if they can be resolved. */
     private primaryKeysForPath;
     private sendError;
@@ -247,8 +329,61 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      * Returns ["posts", "posts/70"] for the example above
      */
     private getParentPaths;
+    /**
+     * Install a channel authorizer — see {@link ChannelAuthorizer}.
+     *
+     * Nothing in the framework calls this yet: it is the seam a rules API will
+     * be built on, kept deliberately separate from the membership floor so the
+     * floor holds whether or not anyone uses it.
+     */
+    setChannelAuthorizer(authorizer: ChannelAuthorizer | undefined): void;
+    /** Which action each channel frame is asking to perform. */
+    private static readonly CHANNEL_ACTIONS;
+    /**
+     * The one door every channel frame comes through.
+     *
+     * Returns synchronously — and so dispatches synchronously — unless an
+     * authorizer is installed. That matters: a client sends `join_channel`,
+     * `presence_state` and `channel_history` back to back on connect, and the
+     * socket's message handler processes each frame up to its first `await`,
+     * so a gate that always yielded would let the reads overtake the join that
+     * is about to authorize them.
+     */
+    private handleChannelMessage;
+    /** Perform an already-authorized channel frame. */
+    private dispatchChannelMessage;
+    /**
+     * Decide whether a client may perform an action on a channel.
+     *
+     * **Membership is the floor.** Reading a channel's presence roster, replaying
+     * its retained history and broadcasting into it all require that this client
+     * has joined it. That is a low bar — joining is open to anyone who can name
+     * the channel — but it is not the bar that was there before, which was none
+     * at all: `channel_history` and `presence_state` answered any socket about
+     * any channel, and a broadcast fanned out to members the sender had never
+     * joined. Two internal tables (`rebase.channel_presence`,
+     * `rebase.channel_messages`) are held outside RLS on the strength of this
+     * check, so it fails closed: an authorizer that throws refuses the frame.
+     *
+     * Anything richer than membership belongs in a {@link ChannelAuthorizer};
+     * this method is where it is consulted, and the only place.
+     */
+    private authorizeChannelAction;
+    /** Tell the client why its channel frame went nowhere, and say so in the log. */
+    private denyChannelAction;
     /** Join a broadcast channel */
     joinChannel(clientId: string, channel: string): void;
+    /**
+     * Say something the first time channels are used on a deployment that is
+     * demonstrably multi-pod while the bus is still the in-memory default.
+     *
+     * Every other warning in this subsystem covers a *configured* bus failing —
+     * the case where the operator already knew a bus mattered. The common
+     * misconfiguration is the opposite one: scaled to two replicas, never
+     * touched `realtime.bus`, and broadcast and presence quietly serve a
+     * fraction of the room. The evidence is already in the process, so use it.
+     */
+    private warnIfMemoryBusOnMultiplePods;
     /** Leave a broadcast channel */
     leaveChannel(clientId: string, channel: string): void;
     /**

package/dist/services/write-denial.d.ts

@@ -0,0 +1,36 @@
+import { SQL } from "drizzle-orm";
+import { PgTable } from "drizzle-orm/pg-core";
+import { ApiError } from "@rebasepro/server";
+import { DrizzleClient } from "../interfaces";
+/**
+ * Explain a write that matched no rows.
+ *
+ * Row-level security filters UPDATE and DELETE through the policy's USING
+ * clause instead of raising: a denied write is reported by Postgres exactly
+ * like a successful one that happened to match nothing. Left unchecked, a
+ * caller cannot tell "denied" from "done" — the write returns 200/204 and the
+ * row is untouched. An agent handed a key with `orders:delete` and no delete
+ * policy is the case that makes it concrete: it deletes nothing, forever, and
+ * is told it worked every time.
+ *
+ * Re-reading the target over the *same* RLS-scoped handle separates the two
+ * cases. A visible row means the policy rejected the write (403); an invisible
+ * one means there is nothing there to write for this caller (404, matching what
+ * a GET would say). The re-read is bound by the caller's own policies, so it
+ * discloses nothing a plain read wouldn't.
+ *
+ * Only reached when zero rows matched, so the happy path pays nothing.
+ *
+ * It lives here, rather than beside its first caller, because every zero-row
+ * write has to answer the same question and answer it identically: the rule
+ * that a readable-but-unwritable target is a 403 is the contract, and a second
+ * copy of it is a second chance to get it wrong.
+ *
+ * @param handle     The RLS-scoped connection the write ran on — not a fresh
+ *                   one, or the re-read would answer for a different caller.
+ * @param table      The table the write targeted (the junction, for a link).
+ * @param conditions The write's own WHERE terms, reused verbatim.
+ * @param denied     Message for the 403: the target is there and was refused.
+ * @param missing    Message for the 404: there is nothing there for this caller.
+ */
+export declare function explainZeroRowWrite(handle: DrizzleClient, table: PgTable, conditions: SQL[], denied: string, missing: string): Promise<ApiError>;