@super-line/server 0.10.1 → 0.10.2

package/dist/index.cjs

@@ -226,6 +226,26 @@ function createSuperLineServer(contract, opts) {
       storeMap[name] = store;
     }
   }
+  const collectionStore = opts.collections;
+  const collectionDefs = c.collections ?? {};
+  const collectionPolicies = { ...opts.policies };
+  for (const p of plugins) {
+    if (!p.policies) continue;
+    for (const [name, policy] of Object.entries(p.policies)) {
+      if (!(name in collectionDefs))
+        throw new Error(
+          `Plugin '${p.name}' policy references unknown collection '${name}' \u2014 register its contract fragment on defineContract({ plugins })`
+        );
+      if (name in collectionPolicies)
+        throw new Error(`Plugin '${p.name}' policy for collection '${name}' collides with an existing policy`);
+      collectionPolicies[name] = policy;
+    }
+  }
+  const checkReferences = opts.checkReferences ?? false;
+  const collIsRelay = collectionStore?.clustering === "relay";
+  const COLL_CHANNEL = "cbatch";
+  const collSubscribers = /* @__PURE__ */ new Map();
+  const connColl = /* @__PURE__ */ new Map();
   const reserved = [];
   for (const p of plugins) {
     if (!p.connection) continue;
@@ -323,6 +343,10 @@ function createSuperLineServer(contract, opts) {
       handleStoreRelay(channel, payload);
       return;
     }
+    if (channel === COLL_CHANNEL) {
+      handleCollectionRelay(payload);
+      return;
+    }
     if (channel.startsWith(PLUGIN)) {
       handlePluginChannel(channel, payload);
       return;
@@ -333,6 +357,7 @@ function createSuperLineServer(contract, opts) {
     if (busSet) deliverBus(payload, busSet);
   });
   void adapter.subscribe(replyChannel);
+  if (collectionStore && collIsRelay) void adapter.subscribe(COLL_CHANNEL);
   function handlePersonal(channel, payload) {
     const set = members.get(channel);
     if (!set) return;
@@ -566,6 +591,7 @@ function createSuperLineServer(contract, opts) {
     raw.onClose((code) => {
       conns.delete(conn);
       for (const channel of conn.channels) leaveChannel(conn, channel);
+      collUnsubAll(conn);
       void adapter.presence?.del(conn.id);
       const goneUserId = opts.identify?.(conn);
       emitTap({
@@ -604,6 +630,9 @@ function createSuperLineServer(contract, opts) {
     else if (frame.t === "srd") await handleStoreRead(conn, frame);
     else if (frame.t === "swr") await handleStoreWrite(conn, frame);
     else if (frame.t === "sclose") handleStoreClose(conn, frame);
+    else if (frame.t === "csub") await handleCollectionSub(conn, frame);
+    else if (frame.t === "cuns") handleCollectionUnsub(conn, frame);
+    else if (frame.t === "cbat") await handleCollectionBatch(conn, frame);
     else if (frame.t === "sres") {
       await handleClientReply(conn, frame.i, { ok: true, d: frame.d });
     } else if (frame.t === "serr") {
@@ -803,6 +832,133 @@ function createSuperLineServer(contract, opts) {
       relaying = false;
     }
   }
+  const collConnState = (conn) => {
+    let s = connColl.get(conn);
+    if (!s) connColl.set(conn, s = { subs: /* @__PURE__ */ new Map(), policy: /* @__PURE__ */ new Map() });
+    return s;
+  };
+  function collUnsubAll(conn) {
+    connColl.delete(conn);
+    for (const set of collSubscribers.values()) set.delete(conn);
+  }
+  async function handleCollectionSub(conn, frame) {
+    if (!collectionStore || !collectionDefs[frame.n]) {
+      conn.send({ t: "err", i: frame.i, code: "NOT_FOUND", m: `Unknown collection: ${frame.n}` });
+      return;
+    }
+    await dispatchOp(conn, frame.i, { kind: "subscribe", name: `collection:${frame.n}`, conn }, async () => {
+      const principal = conn.principal ?? conn.id;
+      const policy = collectionPolicies[frame.n];
+      if (!policy?.read) throw new import_core.SuperLineError("FORBIDDEN", `Read denied: ${frame.n}`);
+      const policyFilter = await policy.read(principal, conn.ctx);
+      const eff = (0, import_core.andFilters)(policyFilter, frame.q.filter);
+      const rows = await collectionStore.snapshot(frame.n, { ...frame.q, filter: eff });
+      const state = collConnState(conn);
+      let subs = state.subs.get(frame.n);
+      if (!subs) state.subs.set(frame.n, subs = /* @__PURE__ */ new Map());
+      subs.set(frame.s, frame.q);
+      state.policy.set(frame.n, policyFilter);
+      let set = collSubscribers.get(frame.n);
+      if (!set) collSubscribers.set(frame.n, set = /* @__PURE__ */ new Set());
+      set.add(conn);
+      conn.send({ t: "res", i: frame.i, d: rows });
+    });
+  }
+  function handleCollectionUnsub(conn, frame) {
+    const state = connColl.get(conn);
+    const subs = state?.subs.get(frame.n);
+    if (!state || !subs) return;
+    subs.delete(frame.s);
+    if (subs.size === 0) {
+      state.subs.delete(frame.n);
+      state.policy.delete(frame.n);
+      collSubscribers.get(frame.n)?.delete(conn);
+    }
+  }
+  async function resolveCollectionOps(ops, principal, ctx) {
+    const store = collectionStore;
+    if (!store) throw new import_core.SuperLineError("NOT_FOUND", "No collection backend configured");
+    const out = [];
+    for (const op of ops) {
+      const def = collectionDefs[op.n];
+      if (!def) throw new import_core.SuperLineError("NOT_FOUND", `Unknown collection: ${op.n}`);
+      const policy = collectionPolicies[op.n];
+      if (!policy?.write) throw new import_core.SuperLineError("FORBIDDEN", `Write denied: ${op.n}`);
+      const prev = await store.read(op.n, op.id);
+      if (op.op === "delete") {
+        if (!await policy.write(principal, "delete", void 0, prev, ctx))
+          throw new import_core.SuperLineError("FORBIDDEN", `Write denied: ${op.n}/${op.id}`);
+        out.push({ op: "delete", n: op.n, id: op.id });
+        continue;
+      }
+      const row = await (0, import_core.validate)(def.schema, op.d);
+      const key = row[def.key];
+      if (typeof key !== "string")
+        throw new import_core.SuperLineError("VALIDATION", `Collection ${op.n} row is missing string key '${def.key}'`);
+      if (key !== op.id) throw new import_core.SuperLineError("VALIDATION", `Row key '${key}' does not match op id '${op.id}'`);
+      if (checkReferences && def.references) {
+        for (const [field, refCollection] of Object.entries(def.references)) {
+          const ref = row[field];
+          if (ref === void 0 || ref === null) continue;
+          if (await store.read(refCollection, String(ref)) === void 0)
+            throw new import_core.SuperLineError("VALIDATION", `Dangling reference: ${op.n}.${field} \u2192 ${refCollection}/${String(ref)} does not exist`);
+        }
+      }
+      const kind = op.op;
+      if (!await policy.write(principal, kind, row, prev, ctx))
+        throw new import_core.SuperLineError("FORBIDDEN", `Write denied: ${op.n}/${op.id}`);
+      out.push({ op: kind, n: op.n, id: op.id, row });
+    }
+    return out;
+  }
+  async function commitCollectionBatch(ops, origin, relay) {
+    if (ops.length === 0 || !collectionStore) return;
+    await collectionStore.apply(ops, origin);
+    if (relay && collIsRelay)
+      void adapter.publish(COLL_CHANNEL, serializer.encode({ ops, origin, nd: instanceId }));
+  }
+  async function handleCollectionBatch(conn, frame) {
+    if (!collectionStore) {
+      conn.send({ t: "err", i: frame.i, code: "NOT_FOUND", m: "No collection backend configured" });
+      return;
+    }
+    await dispatchOp(conn, frame.i, { kind: "request", name: "collection:batch", conn }, async () => {
+      const principal = conn.principal ?? conn.id;
+      const resolved = await resolveCollectionOps(frame.ops, principal, conn.ctx);
+      await commitCollectionBatch(resolved, principal, true);
+      conn.send({ t: "res", i: frame.i, d: null });
+    });
+  }
+  function routeRowChange(change) {
+    const conns2 = collSubscribers.get(change.n);
+    if (!conns2 || conns2.size === 0) return;
+    for (const conn of conns2) {
+      const state = connColl.get(conn);
+      const subs = state?.subs.get(change.n);
+      if (!state || !subs || subs.size === 0) continue;
+      const eff = (0, import_core.andFilters)(state.policy.get(change.n), (0, import_core.orFilters)([...subs.values()].map((q) => q.filter)));
+      const prevlessDelete = change.k === "delete" && change.prev === void 0;
+      const inPrev = prevlessDelete || change.prev !== void 0 && (0, import_core.matchesFilter)(eff, change.prev);
+      const inNext = change.next !== void 0 && (0, import_core.matchesFilter)(eff, change.next);
+      if (!inPrev && !inNext) continue;
+      conn.send({ t: "cchg", n: change.n, k: change.k, id: change.id, d: change.next });
+    }
+  }
+  function handleCollectionRelay(payload) {
+    let env;
+    try {
+      env = serializer.decode(payload);
+    } catch {
+      return;
+    }
+    if (env.nd === instanceId) return;
+    if (!collectionStore || !collIsRelay) return;
+    try {
+      void collectionStore.apply(env.ops, env.origin);
+    } catch {
+    }
+  }
+  if (collectionStore) collectionStore.onChange(routeRowChange);
   function room(name) {
     const channel = ROOM + name;
     return {
@@ -1124,6 +1280,38 @@ function createSuperLineServer(contract, opts) {
       if (!handle) throw new import_core.SuperLineError("NOT_FOUND", `Store not configured: ${name}`);
       return handle;
     },
+    collection(name) {
+      if (!collectionStore) throw new import_core.SuperLineError("NOT_FOUND", "No collection backend configured");
+      const def = collectionDefs[name];
+      if (!def) throw new import_core.SuperLineError("NOT_FOUND", `Collection not declared: ${name}`);
+      const store = collectionStore;
+      const resolve = async (row) => {
+        const v = await (0, import_core.validate)(def.schema, row);
+        const key = v[def.key];
+        if (typeof key !== "string")
+          throw new import_core.SuperLineError("VALIDATION", `Collection ${name} row is missing string key '${def.key}'`);
+        return { id: key, row: v };
+      };
+      return {
+        async insert(row) {
+          const { id, row: v } = await resolve(row);
+          await commitCollectionBatch([{ op: "insert", n: name, id, row: v }], SERVER_ORIGIN, true);
+        },
+        async update(row) {
+          const { id, row: v } = await resolve(row);
+          await commitCollectionBatch([{ op: "update", n: name, id, row: v }], SERVER_ORIGIN, true);
+        },
+        async delete(id) {
+          await commitCollectionBatch([{ op: "delete", n: name, id }], SERVER_ORIGIN, true);
+        },
+        read(id) {
+          return Promise.resolve(store.read(name, id));
+        },
+        snapshot(query) {
+          return Promise.resolve(store.snapshot(name, query ?? {}));
+        }
+      };
+    },
     async close() {
       if (closing) return;
       closing = true;
@@ -1182,6 +1370,8 @@ function createSuperLineServer(contract, opts) {
       },
       store: (name) => api.store(name),
       storeInfos: () => Object.entries(storeMap).map(([name, store]) => ({ name, model: store.model })),
+      collection: (name) => api.collection(name),
+      collectionInfos: () => Object.entries(collectionDefs).map(([name, def]) => ({ name, key: def.key, references: def.references ?? {} })),
       describe: (conn) => buildDescriptor(conn),
       connectionById: (id) => Promise.resolve(presenceOrThrow().get(id)),
       channel: (name) => pluginChannel(pluginName, name)

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { ServerMessageDef, RawConn, Serializer, ServerFrame, EmitData, ConnDescriptor, Adapter, PresenceStore, Contract, RoleOf, NodeStat, SharedEvents, SharedServerRequests, ClientInput, Output, Directional, TapEvent, AccessRules, Resource, Perms, ListOpts, ResourceSummary, SearchOpts, ServerReplica, StoreInfo, CtsOf, ServerInput, ServerStore, Handshake, SharedRequests, AnyData, RoleRequests, Events, DataOf, RoleTopics, SharedTopics, EventData, ServerTransport } from '@super-line/core';
+import { ServerMessageDef, RawConn, Serializer, ServerFrame, EmitData, Expr, CollectionQuery, ConnDescriptor, Adapter, PresenceStore, Contract, RoleOf, NodeStat, SharedEvents, SharedServerRequests, ClientInput, Output, Directional, TapEvent, AccessRules, Resource, Perms, ListOpts, ResourceSummary, SearchOpts, ServerReplica, StoreInfo, CtsOf, ServerInput, ServerStore, Handshake, SharedRequests, AnyData, RoleRequests, Events, DataOf, RoleTopics, SharedTopics, EventData, CollectionName, RowOf, ServerTransport, CollectionStore } from '@super-line/core';
 
 /**
  * A single client connection, passed to handlers as the third argument.
@@ -65,6 +65,46 @@ declare class Conn<Ev = Record<string, ServerMessageDef>, Ctx = unknown, Role ex
  */
 declare function resolvePrincipal(conn: Conn, identify?: (conn: Conn) => string | undefined): string;
 
+type Awaitable$1<T> = T | Promise<T>;
+/** The three row mutations a write policy guards. */
+type WriteOp = 'insert' | 'update' | 'delete';
+/**
+ * Row-security policy for one collection (see ADR-0006, decision 7). Server-side only — callbacks, never
+ * serialized to clients. **Deny-by-default**: omit `read` and clients cannot read the collection at all;
+ * omit `write` and clients cannot write it. Server co-writes via `srv.collection(n)` bypass both.
+ */
+interface CollectionPolicy<Ctx = unknown, Row = unknown> {
+    /**
+     * A caller's visibility filter, ANDed into every snapshot, subscription, and change-route for that caller.
+     * Return `undefined` for "no filter" (the whole collection is visible). Return an {@link Expr} to restrict.
+     * Caveat: it is evaluated at subscribe time; principal-side state captured here (e.g. the caller's channel
+     * list) goes stale until the client resubscribes — row-side predicates re-evaluate on every change naturally.
+     */
+    read?: (principal: string, ctx: Ctx) => Awaitable$1<Expr | undefined>;
+    /**
+     * Per-row write guard. `next` is the incoming row (absent on delete), `prev` the current row (absent on
+     * insert). Return `false` to reject the op — which aborts the whole atomic batch it belongs to.
+     */
+    write?: (principal: string, op: WriteOp, next: Row | undefined, prev: Row | undefined, ctx: Ctx) => Awaitable$1<boolean>;
+}
+/**
+ * Server-authoritative handle for a collection (`srv.collection('messages')`). Writes bypass row policy
+ * (server is authoritative) but are still schema-validated, fan out, and — under relay — replicate across
+ * nodes exactly like a client batch. The door for business-logic mutations that a contract request handler owns.
+ */
+interface ServerCollectionHandle<Row = unknown> {
+    /** Insert a row (its `key` field becomes the id). Throws `CONFLICT` if the id already exists. */
+    insert(row: Row): Promise<void>;
+    /** Replace a row by its `key` (LWW). Throws `NOT_FOUND` if absent. */
+    update(row: Row): Promise<void>;
+    /** Delete a row by id (idempotent). */
+    delete(id: string): Promise<void>;
+    /** Read one row by id, or undefined. */
+    read(id: string): Promise<Row | undefined>;
+    /** Materialize a snapshot (filter/sort/limit); omit the query for the whole collection. Server-side, policy-free. */
+    snapshot(query?: CollectionQuery): Promise<Row[]>;
+}
+
 /**
  * In-process pub/sub bus. Share one bus across multiple servers to simulate
  * multiple nodes in a test (each server gets its own adapter bound to the bus).
@@ -277,9 +317,15 @@ type HandlersFor<S extends Directional> = {
 type PluginHandledKeys<U> = U extends SuperLinePlugin<infer S> ? keyof CtsOf<S> & string : never;
 /** Union of the `clientToServer` keys handled across a plugin tuple `P` (subtracted from `implement`). */
 type HandledKeys<P extends readonly SuperLinePlugin<any>[]> = PluginHandledKeys<P[number]>;
-/** Remove the plugin-handled keys `HK` from every block (each role + `shared`) of a {@link Handlers} map. */
+/**
+ * Remove the plugin-handled keys `HK` from every block (each role + `shared`) of a {@link Handlers} map. A block
+ * a plugin fully owns collapses to `{}` and becomes OPTIONAL — so a host needn't pass an empty `shared: {}` /
+ * `guest: {}` for a role or shared surface a plugin handles entirely.
+ */
 type SubtractHandlers<H, HK extends string> = {
-    [B in keyof H]: Omit<H[B], HK>;
+    [B in keyof H as [keyof Omit<H[B], HK>] extends [never] ? never : B]: Omit<H[B], HK>;
+} & {
+    [B in keyof H as [keyof Omit<H[B], HK>] extends [never] ? B : never]?: Omit<H[B], HK>;
 };
 /**
  * A named, declarative bundle of runtime contributions registered on `plugins: [...]`. All fields
@@ -316,6 +362,14 @@ interface SuperLinePlugin<S extends Directional = {}> {
      * via `srv.store(name)`. A name colliding with a host store or another plugin's store throws at construction.
      */
     stores?: Record<string, ServerStore>;
+    /**
+     * Row-security policies for the collections the plugin's contract fragment declares (see {@link CollectionPolicy}).
+     * Merged into the host's `policies`; a collection already policied by the host or another plugin throws at
+     * construction, and a policy for a collection no fragment declared throws too. Deny-by-default still holds —
+     * a collection nobody policies is server-only. Lets a plugin ship its collections locked down (e.g. deny-all
+     * on secret tables) without the host hand-spreading them.
+     */
+    policies?: Record<string, CollectionPolicy<unknown, unknown>>;
     /**
      * A plugin-owned (reserved) connection class — its own role, handshake negotiation, and parallel contract,
      * served over observer-invisible connections. See {@link PluginConnection}. (Phase 2.)
@@ -407,6 +461,14 @@ interface PluginContext {
     store(name: string): ServerStoreHandle;
     /** Configured stores (host + plugin) and their models. */
     storeInfos(): StoreInfo[];
+    /** Server-authoritative handle for a contract collection (loosely typed here); throws if none is configured. */
+    collection(name: string): ServerCollectionHandle;
+    /** Declared collections (name + key + advisory references) for the schema graph. */
+    collectionInfos(): {
+        name: string;
+        key: string;
+        references: Record<string, string>;
+    }[];
     /** Full cluster descriptor for a local connection (identity + rooms + `describeConn` extras). */
     describe(conn: Conn): ConnDescriptor;
     /** A connection's descriptor anywhere in the cluster (rejects without presence support); undefined if absent. */
@@ -455,6 +517,26 @@ interface SuperLineServerOptions<C extends Contract, A extends AuthResult<C>, P
      * `srv.store.<name>` and `client.store.<name>`. Stores are off-contract and untyped (ADR-0003).
      */
     stores?: Record<string, ServerStore>;
+    /**
+     * The single {@link CollectionStore} backend serving every collection this contract declares (typed rows;
+     * ADR-0006), e.g. `collections: memoryCollections()`. One backend ⇒ one transaction domain, so a
+     * cross-collection batch commits atomically.
+     */
+    collections?: CollectionStore;
+    /**
+     * Row-security policies per collection (see {@link CollectionPolicy}). Deny-by-default: a collection with no
+     * policy is server-only (clients can neither read nor write it). Server co-writes via `srv.collection(n)` bypass them.
+     */
+    policies?: {
+        [N in CollectionName<C>]?: CollectionPolicy<CtxUnion<A>, RowOf<C, N>>;
+    };
+    /**
+     * Opt-in advisory foreign-key checks (see ADR-0006, decision 8). When true, an insert/update whose
+     * `references` field points at a non-existent row is rejected at the accepting node. Best-effort under
+     * relay clustering (no global serialization point) and does NOT resolve intra-batch parent-then-child
+     * references; there are no cascades. Off by default.
+     */
+    checkReferences?: boolean;
     /** Called once per accepted connection. */
     onConnection?: (conn: Conn, ctx: CtxUnion<A>) => void;
     /** Called when a connection closes, with the WebSocket close `code`. */
@@ -495,6 +577,8 @@ interface SuperLineServer<C extends Contract, A extends AuthResult<C>, HK extend
     forRole<R extends RoleOf<C>>(role: R): RoleLens<C, R>;
     /** Server-authoritative handle for a configured Store (`srv.store('scene').create(...)`). Throws `NOT_FOUND` if the name isn't configured. */
     store(name: string): ServerStoreHandle;
+    /** Server-authoritative handle for a contract collection (`srv.collection('messages').insert(...)`), typed by the contract. Throws `NOT_FOUND` if no collection backend is configured or the name isn't declared. */
+    collection<N extends CollectionName<C>>(name: N): ServerCollectionHandle<RowOf<C, N>>;
     close(): Promise<void>;
 }
 /**
@@ -521,4 +605,4 @@ interface SuperLineServer<C extends Contract, A extends AuthResult<C>, HK extend
  */
 declare function createSuperLineServer<C extends Contract, A extends AuthResult<C>, const P extends readonly SuperLinePlugin<any>[] = []>(contract: C, opts: SuperLineServerOptions<C, A, P>): SuperLineServer<C, A, HandledKeys<P>>;
 
-export { type AuthResult, type BusMeta, type ClusterView, Conn, type ConnTarget, type HandledKeys, type Handlers, type HandlersFor, type LocalView, MemoryBus, type Middleware, type MiddlewareInfo, type PluginChannel, type PluginConnection, type PluginContext, type PluginMiddleware, type RoleLens, type Room, type ServerStoreHandle, type SubtractHandlers, type SuperLinePlugin, type SuperLineServer, type SuperLineServerOptions, type UserTarget, createInMemoryAdapter, createSuperLineServer, resolvePrincipal };
+export { type AuthResult, type BusMeta, type ClusterView, type CollectionPolicy, Conn, type ConnTarget, type HandledKeys, type Handlers, type HandlersFor, type LocalView, MemoryBus, type Middleware, type MiddlewareInfo, type PluginChannel, type PluginConnection, type PluginContext, type PluginMiddleware, type RoleLens, type Room, type ServerCollectionHandle, type ServerStoreHandle, type SubtractHandlers, type SuperLinePlugin, type SuperLineServer, type SuperLineServerOptions, type UserTarget, type WriteOp, createInMemoryAdapter, createSuperLineServer, resolvePrincipal };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ServerMessageDef, RawConn, Serializer, ServerFrame, EmitData, ConnDescriptor, Adapter, PresenceStore, Contract, RoleOf, NodeStat, SharedEvents, SharedServerRequests, ClientInput, Output, Directional, TapEvent, AccessRules, Resource, Perms, ListOpts, ResourceSummary, SearchOpts, ServerReplica, StoreInfo, CtsOf, ServerInput, ServerStore, Handshake, SharedRequests, AnyData, RoleRequests, Events, DataOf, RoleTopics, SharedTopics, EventData, ServerTransport } from '@super-line/core';
+import { ServerMessageDef, RawConn, Serializer, ServerFrame, EmitData, Expr, CollectionQuery, ConnDescriptor, Adapter, PresenceStore, Contract, RoleOf, NodeStat, SharedEvents, SharedServerRequests, ClientInput, Output, Directional, TapEvent, AccessRules, Resource, Perms, ListOpts, ResourceSummary, SearchOpts, ServerReplica, StoreInfo, CtsOf, ServerInput, ServerStore, Handshake, SharedRequests, AnyData, RoleRequests, Events, DataOf, RoleTopics, SharedTopics, EventData, CollectionName, RowOf, ServerTransport, CollectionStore } from '@super-line/core';
 
 /**
  * A single client connection, passed to handlers as the third argument.
@@ -65,6 +65,46 @@ declare class Conn<Ev = Record<string, ServerMessageDef>, Ctx = unknown, Role ex
  */
 declare function resolvePrincipal(conn: Conn, identify?: (conn: Conn) => string | undefined): string;
 
+type Awaitable$1<T> = T | Promise<T>;
+/** The three row mutations a write policy guards. */
+type WriteOp = 'insert' | 'update' | 'delete';
+/**
+ * Row-security policy for one collection (see ADR-0006, decision 7). Server-side only — callbacks, never
+ * serialized to clients. **Deny-by-default**: omit `read` and clients cannot read the collection at all;
+ * omit `write` and clients cannot write it. Server co-writes via `srv.collection(n)` bypass both.
+ */
+interface CollectionPolicy<Ctx = unknown, Row = unknown> {
+    /**
+     * A caller's visibility filter, ANDed into every snapshot, subscription, and change-route for that caller.
+     * Return `undefined` for "no filter" (the whole collection is visible). Return an {@link Expr} to restrict.
+     * Caveat: it is evaluated at subscribe time; principal-side state captured here (e.g. the caller's channel
+     * list) goes stale until the client resubscribes — row-side predicates re-evaluate on every change naturally.
+     */
+    read?: (principal: string, ctx: Ctx) => Awaitable$1<Expr | undefined>;
+    /**
+     * Per-row write guard. `next` is the incoming row (absent on delete), `prev` the current row (absent on
+     * insert). Return `false` to reject the op — which aborts the whole atomic batch it belongs to.
+     */
+    write?: (principal: string, op: WriteOp, next: Row | undefined, prev: Row | undefined, ctx: Ctx) => Awaitable$1<boolean>;
+}
+/**
+ * Server-authoritative handle for a collection (`srv.collection('messages')`). Writes bypass row policy
+ * (server is authoritative) but are still schema-validated, fan out, and — under relay — replicate across
+ * nodes exactly like a client batch. The door for business-logic mutations that a contract request handler owns.
+ */
+interface ServerCollectionHandle<Row = unknown> {
+    /** Insert a row (its `key` field becomes the id). Throws `CONFLICT` if the id already exists. */
+    insert(row: Row): Promise<void>;
+    /** Replace a row by its `key` (LWW). Throws `NOT_FOUND` if absent. */
+    update(row: Row): Promise<void>;
+    /** Delete a row by id (idempotent). */
+    delete(id: string): Promise<void>;
+    /** Read one row by id, or undefined. */
+    read(id: string): Promise<Row | undefined>;
+    /** Materialize a snapshot (filter/sort/limit); omit the query for the whole collection. Server-side, policy-free. */
+    snapshot(query?: CollectionQuery): Promise<Row[]>;
+}
+
 /**
  * In-process pub/sub bus. Share one bus across multiple servers to simulate
  * multiple nodes in a test (each server gets its own adapter bound to the bus).
@@ -277,9 +317,15 @@ type HandlersFor<S extends Directional> = {
 type PluginHandledKeys<U> = U extends SuperLinePlugin<infer S> ? keyof CtsOf<S> & string : never;
 /** Union of the `clientToServer` keys handled across a plugin tuple `P` (subtracted from `implement`). */
 type HandledKeys<P extends readonly SuperLinePlugin<any>[]> = PluginHandledKeys<P[number]>;
-/** Remove the plugin-handled keys `HK` from every block (each role + `shared`) of a {@link Handlers} map. */
+/**
+ * Remove the plugin-handled keys `HK` from every block (each role + `shared`) of a {@link Handlers} map. A block
+ * a plugin fully owns collapses to `{}` and becomes OPTIONAL — so a host needn't pass an empty `shared: {}` /
+ * `guest: {}` for a role or shared surface a plugin handles entirely.
+ */
 type SubtractHandlers<H, HK extends string> = {
-    [B in keyof H]: Omit<H[B], HK>;
+    [B in keyof H as [keyof Omit<H[B], HK>] extends [never] ? never : B]: Omit<H[B], HK>;
+} & {
+    [B in keyof H as [keyof Omit<H[B], HK>] extends [never] ? B : never]?: Omit<H[B], HK>;
 };
 /**
  * A named, declarative bundle of runtime contributions registered on `plugins: [...]`. All fields
@@ -316,6 +362,14 @@ interface SuperLinePlugin<S extends Directional = {}> {
      * via `srv.store(name)`. A name colliding with a host store or another plugin's store throws at construction.
      */
     stores?: Record<string, ServerStore>;
+    /**
+     * Row-security policies for the collections the plugin's contract fragment declares (see {@link CollectionPolicy}).
+     * Merged into the host's `policies`; a collection already policied by the host or another plugin throws at
+     * construction, and a policy for a collection no fragment declared throws too. Deny-by-default still holds —
+     * a collection nobody policies is server-only. Lets a plugin ship its collections locked down (e.g. deny-all
+     * on secret tables) without the host hand-spreading them.
+     */
+    policies?: Record<string, CollectionPolicy<unknown, unknown>>;
     /**
      * A plugin-owned (reserved) connection class — its own role, handshake negotiation, and parallel contract,
      * served over observer-invisible connections. See {@link PluginConnection}. (Phase 2.)
@@ -407,6 +461,14 @@ interface PluginContext {
     store(name: string): ServerStoreHandle;
     /** Configured stores (host + plugin) and their models. */
     storeInfos(): StoreInfo[];
+    /** Server-authoritative handle for a contract collection (loosely typed here); throws if none is configured. */
+    collection(name: string): ServerCollectionHandle;
+    /** Declared collections (name + key + advisory references) for the schema graph. */
+    collectionInfos(): {
+        name: string;
+        key: string;
+        references: Record<string, string>;
+    }[];
     /** Full cluster descriptor for a local connection (identity + rooms + `describeConn` extras). */
     describe(conn: Conn): ConnDescriptor;
     /** A connection's descriptor anywhere in the cluster (rejects without presence support); undefined if absent. */
@@ -455,6 +517,26 @@ interface SuperLineServerOptions<C extends Contract, A extends AuthResult<C>, P
      * `srv.store.<name>` and `client.store.<name>`. Stores are off-contract and untyped (ADR-0003).
      */
     stores?: Record<string, ServerStore>;
+    /**
+     * The single {@link CollectionStore} backend serving every collection this contract declares (typed rows;
+     * ADR-0006), e.g. `collections: memoryCollections()`. One backend ⇒ one transaction domain, so a
+     * cross-collection batch commits atomically.
+     */
+    collections?: CollectionStore;
+    /**
+     * Row-security policies per collection (see {@link CollectionPolicy}). Deny-by-default: a collection with no
+     * policy is server-only (clients can neither read nor write it). Server co-writes via `srv.collection(n)` bypass them.
+     */
+    policies?: {
+        [N in CollectionName<C>]?: CollectionPolicy<CtxUnion<A>, RowOf<C, N>>;
+    };
+    /**
+     * Opt-in advisory foreign-key checks (see ADR-0006, decision 8). When true, an insert/update whose
+     * `references` field points at a non-existent row is rejected at the accepting node. Best-effort under
+     * relay clustering (no global serialization point) and does NOT resolve intra-batch parent-then-child
+     * references; there are no cascades. Off by default.
+     */
+    checkReferences?: boolean;
     /** Called once per accepted connection. */
     onConnection?: (conn: Conn, ctx: CtxUnion<A>) => void;
     /** Called when a connection closes, with the WebSocket close `code`. */
@@ -495,6 +577,8 @@ interface SuperLineServer<C extends Contract, A extends AuthResult<C>, HK extend
     forRole<R extends RoleOf<C>>(role: R): RoleLens<C, R>;
     /** Server-authoritative handle for a configured Store (`srv.store('scene').create(...)`). Throws `NOT_FOUND` if the name isn't configured. */
     store(name: string): ServerStoreHandle;
+    /** Server-authoritative handle for a contract collection (`srv.collection('messages').insert(...)`), typed by the contract. Throws `NOT_FOUND` if no collection backend is configured or the name isn't declared. */
+    collection<N extends CollectionName<C>>(name: N): ServerCollectionHandle<RowOf<C, N>>;
     close(): Promise<void>;
 }
 /**
@@ -521,4 +605,4 @@ interface SuperLineServer<C extends Contract, A extends AuthResult<C>, HK extend
  */
 declare function createSuperLineServer<C extends Contract, A extends AuthResult<C>, const P extends readonly SuperLinePlugin<any>[] = []>(contract: C, opts: SuperLineServerOptions<C, A, P>): SuperLineServer<C, A, HandledKeys<P>>;
 
-export { type AuthResult, type BusMeta, type ClusterView, Conn, type ConnTarget, type HandledKeys, type Handlers, type HandlersFor, type LocalView, MemoryBus, type Middleware, type MiddlewareInfo, type PluginChannel, type PluginConnection, type PluginContext, type PluginMiddleware, type RoleLens, type Room, type ServerStoreHandle, type SubtractHandlers, type SuperLinePlugin, type SuperLineServer, type SuperLineServerOptions, type UserTarget, createInMemoryAdapter, createSuperLineServer, resolvePrincipal };
+export { type AuthResult, type BusMeta, type ClusterView, type CollectionPolicy, Conn, type ConnTarget, type HandledKeys, type Handlers, type HandlersFor, type LocalView, MemoryBus, type Middleware, type MiddlewareInfo, type PluginChannel, type PluginConnection, type PluginContext, type PluginMiddleware, type RoleLens, type Room, type ServerCollectionHandle, type ServerStoreHandle, type SubtractHandlers, type SuperLinePlugin, type SuperLineServer, type SuperLineServerOptions, type UserTarget, type WriteOp, createInMemoryAdapter, createSuperLineServer, resolvePrincipal };

package/dist/index.js

@@ -2,7 +2,10 @@
 import {
   jsonSerializer,
   validate,
-  SuperLineError
+  SuperLineError,
+  andFilters,
+  orFilters,
+  matchesFilter
 } from "@super-line/core";
 
 // src/conn.ts
@@ -202,6 +205,26 @@ function createSuperLineServer(contract, opts) {
       storeMap[name] = store;
     }
   }
+  const collectionStore = opts.collections;
+  const collectionDefs = c.collections ?? {};
+  const collectionPolicies = { ...opts.policies };
+  for (const p of plugins) {
+    if (!p.policies) continue;
+    for (const [name, policy] of Object.entries(p.policies)) {
+      if (!(name in collectionDefs))
+        throw new Error(
+          `Plugin '${p.name}' policy references unknown collection '${name}' \u2014 register its contract fragment on defineContract({ plugins })`
+        );
+      if (name in collectionPolicies)
+        throw new Error(`Plugin '${p.name}' policy for collection '${name}' collides with an existing policy`);
+      collectionPolicies[name] = policy;
+    }
+  }
+  const checkReferences = opts.checkReferences ?? false;
+  const collIsRelay = collectionStore?.clustering === "relay";
+  const COLL_CHANNEL = "cbatch";
+  const collSubscribers = /* @__PURE__ */ new Map();
+  const connColl = /* @__PURE__ */ new Map();
   const reserved = [];
   for (const p of plugins) {
     if (!p.connection) continue;
@@ -299,6 +322,10 @@ function createSuperLineServer(contract, opts) {
       handleStoreRelay(channel, payload);
       return;
     }
+    if (channel === COLL_CHANNEL) {
+      handleCollectionRelay(payload);
+      return;
+    }
     if (channel.startsWith(PLUGIN)) {
       handlePluginChannel(channel, payload);
       return;
@@ -309,6 +336,7 @@ function createSuperLineServer(contract, opts) {
     if (busSet) deliverBus(payload, busSet);
   });
   void adapter.subscribe(replyChannel);
+  if (collectionStore && collIsRelay) void adapter.subscribe(COLL_CHANNEL);
   function handlePersonal(channel, payload) {
     const set = members.get(channel);
     if (!set) return;
@@ -542,6 +570,7 @@ function createSuperLineServer(contract, opts) {
     raw.onClose((code) => {
       conns.delete(conn);
       for (const channel of conn.channels) leaveChannel(conn, channel);
+      collUnsubAll(conn);
       void adapter.presence?.del(conn.id);
       const goneUserId = opts.identify?.(conn);
       emitTap({
@@ -580,6 +609,9 @@ function createSuperLineServer(contract, opts) {
     else if (frame.t === "srd") await handleStoreRead(conn, frame);
     else if (frame.t === "swr") await handleStoreWrite(conn, frame);
     else if (frame.t === "sclose") handleStoreClose(conn, frame);
+    else if (frame.t === "csub") await handleCollectionSub(conn, frame);
+    else if (frame.t === "cuns") handleCollectionUnsub(conn, frame);
+    else if (frame.t === "cbat") await handleCollectionBatch(conn, frame);
     else if (frame.t === "sres") {
       await handleClientReply(conn, frame.i, { ok: true, d: frame.d });
     } else if (frame.t === "serr") {
@@ -779,6 +811,133 @@ function createSuperLineServer(contract, opts) {
       relaying = false;
     }
   }
+  const collConnState = (conn) => {
+    let s = connColl.get(conn);
+    if (!s) connColl.set(conn, s = { subs: /* @__PURE__ */ new Map(), policy: /* @__PURE__ */ new Map() });
+    return s;
+  };
+  function collUnsubAll(conn) {
+    connColl.delete(conn);
+    for (const set of collSubscribers.values()) set.delete(conn);
+  }
+  async function handleCollectionSub(conn, frame) {
+    if (!collectionStore || !collectionDefs[frame.n]) {
+      conn.send({ t: "err", i: frame.i, code: "NOT_FOUND", m: `Unknown collection: ${frame.n}` });
+      return;
+    }
+    await dispatchOp(conn, frame.i, { kind: "subscribe", name: `collection:${frame.n}`, conn }, async () => {
+      const principal = conn.principal ?? conn.id;
+      const policy = collectionPolicies[frame.n];
+      if (!policy?.read) throw new SuperLineError("FORBIDDEN", `Read denied: ${frame.n}`);
+      const policyFilter = await policy.read(principal, conn.ctx);
+      const eff = andFilters(policyFilter, frame.q.filter);
+      const rows = await collectionStore.snapshot(frame.n, { ...frame.q, filter: eff });
+      const state = collConnState(conn);
+      let subs = state.subs.get(frame.n);
+      if (!subs) state.subs.set(frame.n, subs = /* @__PURE__ */ new Map());
+      subs.set(frame.s, frame.q);
+      state.policy.set(frame.n, policyFilter);
+      let set = collSubscribers.get(frame.n);
+      if (!set) collSubscribers.set(frame.n, set = /* @__PURE__ */ new Set());
+      set.add(conn);
+      conn.send({ t: "res", i: frame.i, d: rows });
+    });
+  }
+  function handleCollectionUnsub(conn, frame) {
+    const state = connColl.get(conn);
+    const subs = state?.subs.get(frame.n);
+    if (!state || !subs) return;
+    subs.delete(frame.s);
+    if (subs.size === 0) {
+      state.subs.delete(frame.n);
+      state.policy.delete(frame.n);
+      collSubscribers.get(frame.n)?.delete(conn);
+    }
+  }
+  async function resolveCollectionOps(ops, principal, ctx) {
+    const store = collectionStore;
+    if (!store) throw new SuperLineError("NOT_FOUND", "No collection backend configured");
+    const out = [];
+    for (const op of ops) {
+      const def = collectionDefs[op.n];
+      if (!def) throw new SuperLineError("NOT_FOUND", `Unknown collection: ${op.n}`);
+      const policy = collectionPolicies[op.n];
+      if (!policy?.write) throw new SuperLineError("FORBIDDEN", `Write denied: ${op.n}`);
+      const prev = await store.read(op.n, op.id);
+      if (op.op === "delete") {
+        if (!await policy.write(principal, "delete", void 0, prev, ctx))
+          throw new SuperLineError("FORBIDDEN", `Write denied: ${op.n}/${op.id}`);
+        out.push({ op: "delete", n: op.n, id: op.id });
+        continue;
+      }
+      const row = await validate(def.schema, op.d);
+      const key = row[def.key];
+      if (typeof key !== "string")
+        throw new SuperLineError("VALIDATION", `Collection ${op.n} row is missing string key '${def.key}'`);
+      if (key !== op.id) throw new SuperLineError("VALIDATION", `Row key '${key}' does not match op id '${op.id}'`);
+      if (checkReferences && def.references) {
+        for (const [field, refCollection] of Object.entries(def.references)) {
+          const ref = row[field];
+          if (ref === void 0 || ref === null) continue;
+          if (await store.read(refCollection, String(ref)) === void 0)
+            throw new SuperLineError("VALIDATION", `Dangling reference: ${op.n}.${field} \u2192 ${refCollection}/${String(ref)} does not exist`);
+        }
+      }
+      const kind = op.op;
+      if (!await policy.write(principal, kind, row, prev, ctx))
+        throw new SuperLineError("FORBIDDEN", `Write denied: ${op.n}/${op.id}`);
+      out.push({ op: kind, n: op.n, id: op.id, row });
+    }
+    return out;
+  }
+  async function commitCollectionBatch(ops, origin, relay) {
+    if (ops.length === 0 || !collectionStore) return;
+    await collectionStore.apply(ops, origin);
+    if (relay && collIsRelay)
+      void adapter.publish(COLL_CHANNEL, serializer.encode({ ops, origin, nd: instanceId }));
+  }
+  async function handleCollectionBatch(conn, frame) {
+    if (!collectionStore) {
+      conn.send({ t: "err", i: frame.i, code: "NOT_FOUND", m: "No collection backend configured" });
+      return;
+    }
+    await dispatchOp(conn, frame.i, { kind: "request", name: "collection:batch", conn }, async () => {
+      const principal = conn.principal ?? conn.id;
+      const resolved = await resolveCollectionOps(frame.ops, principal, conn.ctx);
+      await commitCollectionBatch(resolved, principal, true);
+      conn.send({ t: "res", i: frame.i, d: null });
+    });
+  }
+  function routeRowChange(change) {
+    const conns2 = collSubscribers.get(change.n);
+    if (!conns2 || conns2.size === 0) return;
+    for (const conn of conns2) {
+      const state = connColl.get(conn);
+      const subs = state?.subs.get(change.n);
+      if (!state || !subs || subs.size === 0) continue;
+      const eff = andFilters(state.policy.get(change.n), orFilters([...subs.values()].map((q) => q.filter)));
+      const prevlessDelete = change.k === "delete" && change.prev === void 0;
+      const inPrev = prevlessDelete || change.prev !== void 0 && matchesFilter(eff, change.prev);
+      const inNext = change.next !== void 0 && matchesFilter(eff, change.next);
+      if (!inPrev && !inNext) continue;
+      conn.send({ t: "cchg", n: change.n, k: change.k, id: change.id, d: change.next });
+    }
+  }
+  function handleCollectionRelay(payload) {
+    let env;
+    try {
+      env = serializer.decode(payload);
+    } catch {
+      return;
+    }
+    if (env.nd === instanceId) return;
+    if (!collectionStore || !collIsRelay) return;
+    try {
+      void collectionStore.apply(env.ops, env.origin);
+    } catch {
+    }
+  }
+  if (collectionStore) collectionStore.onChange(routeRowChange);
   function room(name) {
     const channel = ROOM + name;
     return {
@@ -1100,6 +1259,38 @@ function createSuperLineServer(contract, opts) {
       if (!handle) throw new SuperLineError("NOT_FOUND", `Store not configured: ${name}`);
       return handle;
     },
+    collection(name) {
+      if (!collectionStore) throw new SuperLineError("NOT_FOUND", "No collection backend configured");
+      const def = collectionDefs[name];
+      if (!def) throw new SuperLineError("NOT_FOUND", `Collection not declared: ${name}`);
+      const store = collectionStore;
+      const resolve = async (row) => {
+        const v = await validate(def.schema, row);
+        const key = v[def.key];
+        if (typeof key !== "string")
+          throw new SuperLineError("VALIDATION", `Collection ${name} row is missing string key '${def.key}'`);
+        return { id: key, row: v };
+      };
+      return {
+        async insert(row) {
+          const { id, row: v } = await resolve(row);
+          await commitCollectionBatch([{ op: "insert", n: name, id, row: v }], SERVER_ORIGIN, true);
+        },
+        async update(row) {
+          const { id, row: v } = await resolve(row);
+          await commitCollectionBatch([{ op: "update", n: name, id, row: v }], SERVER_ORIGIN, true);
+        },
+        async delete(id) {
+          await commitCollectionBatch([{ op: "delete", n: name, id }], SERVER_ORIGIN, true);
+        },
+        read(id) {
+          return Promise.resolve(store.read(name, id));
+        },
+        snapshot(query) {
+          return Promise.resolve(store.snapshot(name, query ?? {}));
+        }
+      };
+    },
     async close() {
       if (closing) return;
       closing = true;
@@ -1158,6 +1349,8 @@ function createSuperLineServer(contract, opts) {
       },
       store: (name) => api.store(name),
       storeInfos: () => Object.entries(storeMap).map(([name, store]) => ({ name, model: store.model })),
+      collection: (name) => api.collection(name),
+      collectionInfos: () => Object.entries(collectionDefs).map(([name, def]) => ({ name, key: def.key, references: def.references ?? {} })),
       describe: (conn) => buildDescriptor(conn),
       connectionById: (id) => Promise.resolve(presenceOrThrow().get(id)),
       channel: (name) => pluginChannel(pluginName, name)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@super-line/server",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "type": "module",
   "description": "Realtime data-bus server for super-line — requests, events, rooms, topics, stores, pluggable transports & adapters.",
   "license": "MIT",
@@ -47,7 +47,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@super-line/core": "^0.10.0"
+    "@super-line/core": "^0.10.1"
   },
   "devDependencies": {
     "@chainsafe/libp2p-noise": "^17.0.0",
@@ -68,15 +68,15 @@
     "zeromq": "^6.0.0",
     "zod": "^3.24.1",
     "zod-to-json-schema": "^3.25.2",
-    "@super-line/client": "0.8.0",
+    "@super-line/adapter-libp2p": "0.6.0",
     "@super-line/adapter-zeromq": "0.5.0",
-    "@super-line/adapter-rabbitmq": "0.5.0",
     "@super-line/adapter-redis": "0.5.0",
     "@super-line/plugin-inspector": "0.1.0",
-    "@super-line/transport-http": "0.5.0",
-    "@super-line/transport-websocket": "0.6.0",
+    "@super-line/adapter-rabbitmq": "0.5.0",
+    "@super-line/client": "0.8.0",
     "@super-line/transport-loopback": "0.5.0",
-    "@super-line/adapter-libp2p": "0.6.0"
+    "@super-line/transport-websocket": "0.6.0",
+    "@super-line/transport-http": "0.5.0"
   },
   "optionalDependencies": {
     "@standard-community/standard-json": "^0.3.5"