@super-line/server 0.10.1 → 0.11.0

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, CrdtServerReplica, DocListOpts, DocSummary, ConnDescriptor, Adapter, PresenceStore, Contract, RoleOf, NodeStat, SharedEvents, SharedServerRequests, ClientInput, Output, Directional, TapEvent, CtsOf, ServerInput, Handshake, SharedRequests, AnyData, RoleRequests, Events, DataOf, RoleTopics, SharedTopics, EventData, CollectionName, CrdtCollectionName, DocOf, RowOf, ServerTransport, CollectionStore, CrdtCollectionStore } from '@super-line/core';
 
 /**
  * A single client connection, passed to handlers as the third argument.
@@ -65,6 +65,76 @@ 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[]>;
+}
+/**
+ * Access policy for a CRDT document collection (ADR-0007, Q7). Guard-shaped — not the RLS filter shape of
+ * {@link CollectionPolicy}, because CRDT collections are opened by id (no subset to filter). **Deny-by-default**.
+ * Server co-writes via `srv.collection(n)` bypass both.
+ */
+interface CrdtCollectionPolicy<Ctx = unknown, Doc = unknown> {
+    /** May this principal open `id`? Gets the post-merge plaintext `snapshot` (content-based auth like RLS reading a row). */
+    read?: (principal: string, id: string, snapshot: Doc | undefined, ctx: Ctx) => Awaitable$1<boolean>;
+    /** May this principal write to `id`? (Creation is server-authoritative — Q10 — so there is no `create` op here.) */
+    write?: (principal: string, id: string, ctx: Ctx) => Awaitable$1<boolean>;
+}
+/**
+ * Server-authoritative handle for a CRDT document collection (`srv.collection('scenes')`). Creation is
+ * server-only (Q10): `create` validates the initial doc and materializes it; `open` returns a reactive
+ * co-writer whose mutations fan out like a relayed client delta. Policy-free (server is authoritative).
+ */
+interface ServerCrdtCollectionHandle<Doc = unknown> {
+    /** Create a document with pre-validated initial data. Throws `CONFLICT` if the id exists. */
+    create(id: string, data: Doc): Promise<void>;
+    /** Open a reactive co-writer over an existing document. `origin` (default `"server"`) attributes its writes. */
+    open(id: string, opts?: {
+        origin?: string;
+    }): CrdtServerReplica;
+    /** Read the current plaintext snapshot of a document, or undefined if absent. */
+    read(id: string): Promise<Doc | undefined>;
+    /** Delete a document (idempotent), fanning the deletion cluster-wide. */
+    delete(id: string): Promise<void>;
+    /** Enumerate document ids + summaries (no content query). */
+    list(opts?: DocListOpts): Promise<DocSummary[]>;
+}
+
 /**
  * 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).
@@ -226,46 +296,6 @@ interface RoleLens<C extends Contract, R extends RoleOf<C>> {
     /** Publish to a topic in role `R`'s surface (reaches that role's subscribers). */
     publish<T extends keyof RoleTopics<C, R>>(topic: T, data: EmitData<RoleTopics<C, R>[T]>): void;
 }
-/**
- * Server-side handle for one configured Store, reached via `srv.store.<name>`. The server is
- * authoritative: it creates Resources, grants/revokes access, and may co-write. `data` is untyped
- * (stores are off-contract — see ADR-0003); callers assert the shape.
- */
-interface ServerStoreHandle {
-    /** Create a Resource with initial data + access rules (deny-by-default for everyone unlisted). */
-    create(id: string, data: unknown, accessRules: AccessRules): Promise<void>;
-    /** Read a Resource (data + accessRules), or undefined if absent. */
-    read(id: string): Promise<Resource | undefined>;
-    /**
-     * Server co-write: replace the Resource's value (LWW), fanned out to subscribers stamped with `origin`
-     * (default `"server"`) for echo-break + inspector attribution — mirrors {@link ServerStore.open}'s origin.
-     */
-    write(id: string, data: unknown, opts?: {
-        origin?: string;
-    }): Promise<void>;
-    /** Grant a principal read/write on a Resource. */
-    grant(id: string, principal: string, perms: Perms): Promise<void>;
-    /** Revoke a principal's access to a Resource entirely. */
-    revoke(id: string, principal: string): Promise<void>;
-    /** Delete a Resource. */
-    delete(id: string): Promise<void>;
-    /**
-     * Summaries of this store's Resources, server-side filtered / sorted / paginated per {@link ListOpts}
-     * (omit `opts` for every Resource, id-ascending). Forwards to {@link ServerStore.list}.
-     */
-    list(opts?: ListOpts): Promise<ResourceSummary[]>;
-    /** Distinct principals granted anywhere in this store (store-global). Forwards to {@link ServerStore.searchPrincipals}. */
-    searchPrincipals(opts: SearchOpts): Promise<string[]>;
-    /**
-     * Open a reactive in-process co-writer over a Resource's canonical state — the server half's mirror of
-     * `client.store(name).open(id)`. Reactive reads, merging `update`, and surgical `delete(path)` (the only
-     * way to remove a key server-side), all server-authoritative and fanned out to subscribers. `origin`
-     * (default `"server"`) tags its Changes for inspector attribution. Throws if the store has no `open`.
-     */
-    open(id: string, opts?: {
-        origin?: string;
-    }): ServerReplica;
-}
 /**
  * Handlers a plugin provides for its paired surface `S` (ADR-0004): one per `clientToServer` key,
  * typed from `S`. `ctx`/`conn` are loose — a plugin is written independently of the host's per-role ctx.
@@ -277,9 +307,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
@@ -312,10 +348,13 @@ interface SuperLinePlugin<S extends Directional = {}> {
      */
     handlers?: (ctx: PluginContext) => HandlersFor<S>;
     /**
-     * Server halves of Store pairs the plugin contributes, merged into the host's `stores` and reachable
-     * via `srv.store(name)`. A name colliding with a host store or another plugin's store throws at construction.
+     * 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.
      */
-    stores?: Record<string, ServerStore>;
+    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.)
@@ -403,10 +442,14 @@ interface PluginContext {
         readonly size: number;
         readonly connections: readonly Conn[];
     };
-    /** Server-authoritative handle for a configured store (incl. plugin-contributed stores). */
-    store(name: string): ServerStoreHandle;
-    /** Configured stores (host + plugin) and their models. */
-    storeInfos(): StoreInfo[];
+    /** Server-authoritative handle for a contract collection (loosely typed here as the LWW row handle — the surface plugins/inspector use); 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. */
@@ -450,11 +493,32 @@ interface SuperLineServerOptions<C extends Contract, A extends AuthResult<C>, P
         maxMissed?: number;
     } | false;
     /**
-     * Pluggable persisted-state Stores, keyed by name (`{ scene: crdtStoreServer(), config: memoryStoreServer() }`).
-     * Each is the server half of a Store pair; the client passes the matching client halves. Surfaced as
-     * `srv.store.<name>` and `client.store.<name>`. Stores are off-contract and untyped (ADR-0003).
+     * 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;
+    /**
+     * The {@link CrdtCollectionStore} backend serving this contract's CRDT document collections (ADR-0007),
+     * e.g. `crdtCollections: crdtMemoryCollections()`. A backend per family: CRDT docs never join a
+     * cross-collection atomic batch, so they get their own backend, separate from `collections`.
+     */
+    crdtCollections?: CrdtCollectionStore;
+    /**
+     * Access policies per collection. Deny-by-default: a collection with no policy is server-only. LWW row
+     * collections take an RLS-style {@link CollectionPolicy} (read → filter); CRDT document collections take a
+     * guard-shaped {@link CrdtCollectionPolicy} (read → bool). Server co-writes via `srv.collection(n)` bypass them.
      */
-    stores?: Record<string, ServerStore>;
+    policies?: {
+        [N in CollectionName<C>]?: N extends CrdtCollectionName<C> ? CrdtCollectionPolicy<CtxUnion<A>, DocOf<C, N>> : 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`. */
@@ -493,8 +557,13 @@ interface SuperLineServer<C extends Contract, A extends AuthResult<C>, HK extend
     subscribe<T extends keyof SharedTopics<C>>(topic: T, handler: (data: EventData<SharedTopics<C>[T]>, meta: BusMeta) => void): () => void;
     /** Lens for role-scoped sends, e.g. forRole('user').publish('feed', data). */
     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, typed by the contract: an LWW row collection gives
+     * `ServerCollectionHandle` (`insert`/`update`/`batch`), a CRDT document collection gives
+     * `ServerCrdtCollectionHandle` (`create`/`open`). Throws `NOT_FOUND` if no matching backend is configured
+     * or the name isn't declared.
+     */
+    collection<N extends CollectionName<C>>(name: N): N extends CrdtCollectionName<C> ? ServerCrdtCollectionHandle<DocOf<C, N>> : ServerCollectionHandle<RowOf<C, N>>;
     close(): Promise<void>;
 }
 /**
@@ -521,4 +590,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 CrdtCollectionPolicy, 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 ServerCrdtCollectionHandle, 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, CrdtServerReplica, DocListOpts, DocSummary, ConnDescriptor, Adapter, PresenceStore, Contract, RoleOf, NodeStat, SharedEvents, SharedServerRequests, ClientInput, Output, Directional, TapEvent, CtsOf, ServerInput, Handshake, SharedRequests, AnyData, RoleRequests, Events, DataOf, RoleTopics, SharedTopics, EventData, CollectionName, CrdtCollectionName, DocOf, RowOf, ServerTransport, CollectionStore, CrdtCollectionStore } from '@super-line/core';
 
 /**
  * A single client connection, passed to handlers as the third argument.
@@ -65,6 +65,76 @@ 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[]>;
+}
+/**
+ * Access policy for a CRDT document collection (ADR-0007, Q7). Guard-shaped — not the RLS filter shape of
+ * {@link CollectionPolicy}, because CRDT collections are opened by id (no subset to filter). **Deny-by-default**.
+ * Server co-writes via `srv.collection(n)` bypass both.
+ */
+interface CrdtCollectionPolicy<Ctx = unknown, Doc = unknown> {
+    /** May this principal open `id`? Gets the post-merge plaintext `snapshot` (content-based auth like RLS reading a row). */
+    read?: (principal: string, id: string, snapshot: Doc | undefined, ctx: Ctx) => Awaitable$1<boolean>;
+    /** May this principal write to `id`? (Creation is server-authoritative — Q10 — so there is no `create` op here.) */
+    write?: (principal: string, id: string, ctx: Ctx) => Awaitable$1<boolean>;
+}
+/**
+ * Server-authoritative handle for a CRDT document collection (`srv.collection('scenes')`). Creation is
+ * server-only (Q10): `create` validates the initial doc and materializes it; `open` returns a reactive
+ * co-writer whose mutations fan out like a relayed client delta. Policy-free (server is authoritative).
+ */
+interface ServerCrdtCollectionHandle<Doc = unknown> {
+    /** Create a document with pre-validated initial data. Throws `CONFLICT` if the id exists. */
+    create(id: string, data: Doc): Promise<void>;
+    /** Open a reactive co-writer over an existing document. `origin` (default `"server"`) attributes its writes. */
+    open(id: string, opts?: {
+        origin?: string;
+    }): CrdtServerReplica;
+    /** Read the current plaintext snapshot of a document, or undefined if absent. */
+    read(id: string): Promise<Doc | undefined>;
+    /** Delete a document (idempotent), fanning the deletion cluster-wide. */
+    delete(id: string): Promise<void>;
+    /** Enumerate document ids + summaries (no content query). */
+    list(opts?: DocListOpts): Promise<DocSummary[]>;
+}
+
 /**
  * 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).
@@ -226,46 +296,6 @@ interface RoleLens<C extends Contract, R extends RoleOf<C>> {
     /** Publish to a topic in role `R`'s surface (reaches that role's subscribers). */
     publish<T extends keyof RoleTopics<C, R>>(topic: T, data: EmitData<RoleTopics<C, R>[T]>): void;
 }
-/**
- * Server-side handle for one configured Store, reached via `srv.store.<name>`. The server is
- * authoritative: it creates Resources, grants/revokes access, and may co-write. `data` is untyped
- * (stores are off-contract — see ADR-0003); callers assert the shape.
- */
-interface ServerStoreHandle {
-    /** Create a Resource with initial data + access rules (deny-by-default for everyone unlisted). */
-    create(id: string, data: unknown, accessRules: AccessRules): Promise<void>;
-    /** Read a Resource (data + accessRules), or undefined if absent. */
-    read(id: string): Promise<Resource | undefined>;
-    /**
-     * Server co-write: replace the Resource's value (LWW), fanned out to subscribers stamped with `origin`
-     * (default `"server"`) for echo-break + inspector attribution — mirrors {@link ServerStore.open}'s origin.
-     */
-    write(id: string, data: unknown, opts?: {
-        origin?: string;
-    }): Promise<void>;
-    /** Grant a principal read/write on a Resource. */
-    grant(id: string, principal: string, perms: Perms): Promise<void>;
-    /** Revoke a principal's access to a Resource entirely. */
-    revoke(id: string, principal: string): Promise<void>;
-    /** Delete a Resource. */
-    delete(id: string): Promise<void>;
-    /**
-     * Summaries of this store's Resources, server-side filtered / sorted / paginated per {@link ListOpts}
-     * (omit `opts` for every Resource, id-ascending). Forwards to {@link ServerStore.list}.
-     */
-    list(opts?: ListOpts): Promise<ResourceSummary[]>;
-    /** Distinct principals granted anywhere in this store (store-global). Forwards to {@link ServerStore.searchPrincipals}. */
-    searchPrincipals(opts: SearchOpts): Promise<string[]>;
-    /**
-     * Open a reactive in-process co-writer over a Resource's canonical state — the server half's mirror of
-     * `client.store(name).open(id)`. Reactive reads, merging `update`, and surgical `delete(path)` (the only
-     * way to remove a key server-side), all server-authoritative and fanned out to subscribers. `origin`
-     * (default `"server"`) tags its Changes for inspector attribution. Throws if the store has no `open`.
-     */
-    open(id: string, opts?: {
-        origin?: string;
-    }): ServerReplica;
-}
 /**
  * Handlers a plugin provides for its paired surface `S` (ADR-0004): one per `clientToServer` key,
  * typed from `S`. `ctx`/`conn` are loose — a plugin is written independently of the host's per-role ctx.
@@ -277,9 +307,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
@@ -312,10 +348,13 @@ interface SuperLinePlugin<S extends Directional = {}> {
      */
     handlers?: (ctx: PluginContext) => HandlersFor<S>;
     /**
-     * Server halves of Store pairs the plugin contributes, merged into the host's `stores` and reachable
-     * via `srv.store(name)`. A name colliding with a host store or another plugin's store throws at construction.
+     * 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.
      */
-    stores?: Record<string, ServerStore>;
+    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.)
@@ -403,10 +442,14 @@ interface PluginContext {
         readonly size: number;
         readonly connections: readonly Conn[];
     };
-    /** Server-authoritative handle for a configured store (incl. plugin-contributed stores). */
-    store(name: string): ServerStoreHandle;
-    /** Configured stores (host + plugin) and their models. */
-    storeInfos(): StoreInfo[];
+    /** Server-authoritative handle for a contract collection (loosely typed here as the LWW row handle — the surface plugins/inspector use); 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. */
@@ -450,11 +493,32 @@ interface SuperLineServerOptions<C extends Contract, A extends AuthResult<C>, P
         maxMissed?: number;
     } | false;
     /**
-     * Pluggable persisted-state Stores, keyed by name (`{ scene: crdtStoreServer(), config: memoryStoreServer() }`).
-     * Each is the server half of a Store pair; the client passes the matching client halves. Surfaced as
-     * `srv.store.<name>` and `client.store.<name>`. Stores are off-contract and untyped (ADR-0003).
+     * 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;
+    /**
+     * The {@link CrdtCollectionStore} backend serving this contract's CRDT document collections (ADR-0007),
+     * e.g. `crdtCollections: crdtMemoryCollections()`. A backend per family: CRDT docs never join a
+     * cross-collection atomic batch, so they get their own backend, separate from `collections`.
+     */
+    crdtCollections?: CrdtCollectionStore;
+    /**
+     * Access policies per collection. Deny-by-default: a collection with no policy is server-only. LWW row
+     * collections take an RLS-style {@link CollectionPolicy} (read → filter); CRDT document collections take a
+     * guard-shaped {@link CrdtCollectionPolicy} (read → bool). Server co-writes via `srv.collection(n)` bypass them.
      */
-    stores?: Record<string, ServerStore>;
+    policies?: {
+        [N in CollectionName<C>]?: N extends CrdtCollectionName<C> ? CrdtCollectionPolicy<CtxUnion<A>, DocOf<C, N>> : 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`. */
@@ -493,8 +557,13 @@ interface SuperLineServer<C extends Contract, A extends AuthResult<C>, HK extend
     subscribe<T extends keyof SharedTopics<C>>(topic: T, handler: (data: EventData<SharedTopics<C>[T]>, meta: BusMeta) => void): () => void;
     /** Lens for role-scoped sends, e.g. forRole('user').publish('feed', data). */
     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, typed by the contract: an LWW row collection gives
+     * `ServerCollectionHandle` (`insert`/`update`/`batch`), a CRDT document collection gives
+     * `ServerCrdtCollectionHandle` (`create`/`open`). Throws `NOT_FOUND` if no matching backend is configured
+     * or the name isn't declared.
+     */
+    collection<N extends CollectionName<C>>(name: N): N extends CrdtCollectionName<C> ? ServerCrdtCollectionHandle<DocOf<C, N>> : ServerCollectionHandle<RowOf<C, N>>;
     close(): Promise<void>;
 }
 /**
@@ -521,4 +590,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 CrdtCollectionPolicy, 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 ServerCrdtCollectionHandle, type SubtractHandlers, type SuperLinePlugin, type SuperLineServer, type SuperLineServerOptions, type UserTarget, type WriteOp, createInMemoryAdapter, createSuperLineServer, resolvePrincipal };