@shivaedev/contract 0.18.0 → 0.19.1

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.19.1 - 2026-10-29
+
+### Fixed
+
+- Automatic live tracking no longer resubscribes, and refetches every tracked query, when a query is read again after the garbage collector reclaimed its atom. A query's tracking id now follows its tag and payload instead of the atom object AtomRpc holds weakly.
+
+## 0.19.0 - 2026-10-28
+
+### Added
+
+- `@shivaedev/contract/bind.ts` builds a bound HTTP RPC client and atom runtime from a contract and URL, with an inferred request transform for cookies or bearer tokens.
+- `@shivaedev/react/client/useNow.ts` exports `useNow(interval, runtime?)` to render the runtime's Effect clock and refresh on the requested interval, including with TestClock.
+- Declare collection policies beside module contracts with `ModuleReadPolicies` and combine them with `mergeReadPolicies`. Unclaimed collections are denied. Each policy receives the request's optional viewer.
+- The application host accepts a merged `readPolicy` and checks queries and live hints inside native session middleware, using its resolved identity without another session lookup. Policies can use application services and return `Forbidden` or `AuthUnavailable`.
+- Query authorization and live-hint filtering check keys concurrently so native `Effect.request` resolvers can batch membership checks. Plain Effect policies remain supported.
+
+### Fixed
+
+- Live queries accept inputs JSON cannot encode, such as bigint ids.
+- Enforce declared query read policies at the hosted RPC handler boundary, including contracts without identity middleware, whose viewer is anonymous. Query RPC error schemas include `QueryReadDenied` so native clients receive typed refusals before handlers run.
+- Keep collection methods and untyped schema internals from making data parameters appear to carry callable services. Direct service implementations, nested dependency fields and service arrays remain subject to `effect/service-parameters`.
+
+### Breaking
+
+- Move key imports from `@shivaedev/contract/keys.ts` to `@shivaedev/changes/keys.ts`. Declare bucket fields with `collection(name, idSchema, fields)` and publish affected buckets alongside record keys.
+- Replace collection policy maps, `mergeReadPolicies`, `ReadPolicy` and `ReadPolicyMemoWindow` with each query's `readPolicy(payload, viewer)`. Declare the same query's live scope with `reads(payload, viewer)`. Bound query atoms and subscriptions refuse missing policies with a declaration error; one-off query `run` calls remain available. Denied queries refuse the entire subscription. Server adapters replace `QueryReads` and `ChangesReads` with `QueryDefinition` and `ChangesQueries`. Custom middleware calls `authorizeReads(effect, request, viewer)` and declares `MissingReadPolicy` and `QueryReadDenied` errors.
+- Custom subscription adapters yield `ChangesQueries.resolve(references)`, call `querySubscription(requests, viewer)` and pass the authorized result to `makeLiveServer.subscribe(subscription, context)`. Metadata values expose `QueryDefinition.definition` and `CommandInvalidation.invalidates` instead of bare definitions and callbacks. Yield the Effect returned by `queryKeys(queries, references)` when projecting keys for a custom stream. `resolveChanges` supplies the authorized subscription in hosted applications. Changed hints can carry query positions so bindings can rerun session-scoped reads without deriving session scopes in the browser.
+- Remove `appHost`'s `readPolicy` option and module policy registration. Session and permission middleware apply query policies using the current session viewer. Handle the new typed policy errors in native clients, including `QueryReadDenied` on query RPCs without identity middleware; widen explicit query error annotations accordingly.
+- Replace `sessionCommandChanges` with `commandChanges` for custom session middleware. Command invalidation callbacks can receive the session viewer as their third argument. Announce viewer buckets there; background writers must explicitly publish those bucket keys after commit.
+- Built-in admin queries declare their permission policies alongside their schemas and read scopes. Consumers keep supplying the existing session and permission middleware layers.
+- Local Work Board and Fleet queries declare their existing loopback read access explicitly so their generated live subscriptions remain available.
+- `authorizeReads` now takes `(effect, request, policy, viewer, denied)`, and policies take `(key, viewer)`. Pass `Option.some(resolvedIdentity)` or `Option.none()` before the denial effect. Existing unary policy functions may ignore the new viewer argument. Apps using `appHost` can replace custom read middleware with its `readPolicy` option and merge their modules' policy maps.
+
 ## 0.18.0 - 2026-10-27
 
 ### Added

package/README.md

@@ -7,16 +7,16 @@ Declare a feature's queries, commands, streams, expected failures and refresh de
 A feature often repeats its inputs, results and errors on both sides of an RPC boundary, then separately wires which views a write should refresh. Those copies are easy to make disagree. Put the boundary and its dependencies together:
 
 ```ts
-import { Schema } from "effect";
+import { Effect, Schema } from "effect";
 import { contract } from "@shivaedev/contract/contract.ts";
-import { collection } from "@shivaedev/contract/keys.ts";
+import { collection } from "@shivaedev/changes/keys.ts";
 import { command, query } from "@shivaedev/contract/operation.ts";
 
 const notes = collection("notes", Schema.Number);
-const List = query("list", { reads: () => [notes.list], success: Schema.Array(Schema.String) });
+const List = query("list", { readPolicy: () => Effect.succeed(true), reads: () => [notes.list], success: Schema.Array(Schema.String) });
 const Rename = command("rename", {
-  payload: { id: Schema.Number, title: Schema.String },
-  invalidates: ({ id }) => [notes.item(id)],
+	payload: { id: Schema.Number, title: Schema.String },
+	invalidates: ({ id }) => [notes.item(id)],
 });
 const Notes = contract("notes", { queries: [List], commands: [Rename] });
 ```
@@ -40,47 +40,49 @@ Optional live hints use those same keys. A hint asks for another read; it does n
 Keep the shared declaration in a module that both server and client can import:
 
 ```ts
-import { Schema } from "effect";
+import { Effect, Schema } from "effect";
 import { contract } from "@shivaedev/contract/contract.ts";
-import { collection } from "@shivaedev/contract/keys.ts";
+import { collection } from "@shivaedev/changes/keys.ts";
 import { command, query } from "@shivaedev/contract/operation.ts";
 import { fieldRejection } from "@shivaedev/contract/rejection.ts";
 
 export class Note extends Schema.Class<Note>("Note")({
-  body: Schema.String,
-  id: Schema.Number,
-  title: Schema.String,
+	body: Schema.String,
+	id: Schema.Number,
+	title: Schema.String,
 }) {}
 export const Draft = Schema.Struct({ body: Schema.String, title: Schema.String });
 export class NoteMissing extends Schema.TaggedError<NoteMissing>()("NoteMissing", { id: Schema.Number }) {}
 export const notes = collection("notes", Note.fields.id);
 
 export const Get = query("get", {
-  payload: { id: Schema.Number },
-  success: Note,
-  rejections: { NoteMissing },
-  reads: ({ id }) => [notes.item(id)],
+	readPolicy: () => Effect.succeed(true),
+	payload: { id: Schema.Number },
+	success: Note,
+	rejections: { NoteMissing },
+	reads: ({ id }) => [notes.item(id)],
 });
 export const List = query("list", {
-  success: Schema.Array(Note),
-  reads: () => [notes.list],
+	readPolicy: () => Effect.succeed(true),
+	success: Schema.Array(Note),
+	reads: () => [notes.list],
 });
 export const Rename = command("rename", {
-  payload: { id: Schema.Number, title: Schema.String },
-  success: Note,
-  rejections: { NoteMissing, Invalid: fieldRejection(Draft, ["title"]) },
-  invalidates: ({ id }) => [notes.item(id)],
+	payload: { id: Schema.Number, title: Schema.String },
+	success: Note,
+	rejections: { NoteMissing, Invalid: fieldRejection(Draft, ["title"]) },
+	invalidates: ({ id }) => [notes.item(id)],
 });
 export const Create = command("create", {
-  payload: Draft,
-  success: Note,
-  rejections: { Invalid: fieldRejection(Draft) },
-  invalidates: (_draft, note) => [notes.item(note.id)],
+	payload: Draft,
+	success: Note,
+	rejections: { Invalid: fieldRejection(Draft) },
+	invalidates: (_draft, note) => [notes.item(note.id)],
 });
 export const Notes = contract("notes", { queries: [Get, List], commands: [Rename, Create] });
 ```
 
-Save this module as `notes.ts`. The payload can be struct fields, as in `Get`, or a schema, as in `Create`. An omitted payload or success is `Schema.Void`; no declared rejections gives `Schema.Never`. The `reads` callback receives the decoded payload. `invalidates` receives the decoded payload and successful result, so a create call can invalidate the ID the server assigned.
+Save this module as `notes.ts`. The payload can be struct fields, as in `Get`, or a schema, as in `Create`. An omitted payload or success is `Schema.Void`; no declared rejections gives `Schema.Never`. The server resolves `reads` with the decoded payload and session viewer. For local command dependencies, the browser also evaluates it with `Option.none()`; return no viewer keys for that case. Authorized subscription scopes always come from the server. `invalidates` receives the decoded payload, successful result and optional session viewer, so a create call can invalidate the ID the server assigned.
 
 The collection's ID schema gives `item` its ID type. Here, `notes.item` takes a number. Query and command callbacks retain their payload and result types, including when the operations are declared inline inside `contract`.
 
@@ -91,14 +93,14 @@ Operation names must differ within a contract, including across queries, command
 Import the shared expected failures from `@shivaedev/errors/taxonomy.ts`: `NotFound`, `Unauthorized`, `Forbidden`, `BadRequest`, `Conflict`, `PreconditionFailed`, `TooManyRequests`, `AuthUnavailable`, `InternalServerError` and `ServiceUnavailable`. Each class is a tagged error schema with a string `message`; `BadRequest` and `Conflict` also accept an optional string `field`. Declare only the failures an operation can return:
 
 ```ts
-import { Schema } from "effect";
+import { Effect, Schema } from "effect";
 import { Rpc } from "effect/rpc";
 import { BadRequest, Conflict } from "@shivaedev/errors/taxonomy.ts";
 
 export const Rename = Rpc.make("Rename", {
-  error: Schema.Union([BadRequest, Conflict]),
-  payload: { name: Schema.String },
-  success: Schema.String,
+	error: Schema.Union([BadRequest, Conflict]),
+	payload: { name: Schema.String },
+	success: Schema.String,
 });
 ```
 
@@ -124,28 +126,35 @@ Implement the contract with native `of` and `toLayer`:
 import { Effect, Ref, Stream } from "effect";
 import { Create, Get, Note, Notes, Rename } from "./notes.ts";
 
-export const NotesHandlers = Notes.toLayer(Effect.gen(function* () {
-  const stored = yield* Ref.make(new Map([
-    [1, new Note({ body: "", id: 1, title: "One" })],
-    [2, new Note({ body: "", id: 2, title: "Two" })],
-  ]));
-  const find = (id: number) => Effect.flatMap(Ref.get(stored), (all) => {
-    const note = all.get(id);
-    return note === undefined ? Get.reject.NoteMissing({ id }) : Effect.succeed(note);
-  });
-  const save = (note: Note) => Ref.update(stored, (all) => new Map([...all, [note.id, note]])).pipe(Effect.as(note));
-  return Notes.of({
-    "notes.$changes": () => Stream.never,
-    "notes.get": ({ id }) => find(id),
-    "notes.list": () => Effect.map(Ref.get(stored), (all) => [...all.values()]),
-    "notes.rename": ({ id, title }) => title.trim() === ""
-      ? Rename.reject.Invalid({ field: "title", message: "Enter a title" })
-      : Effect.flatMap(find(id), (note) => save(new Note({ ...note, title }))),
-    "notes.create": (draft) => draft.title === ""
-      ? Create.reject.Invalid({ field: "title", message: "Enter a title" })
-      : Effect.flatMap(Ref.get(stored), (all) => save(new Note({ id: all.size + 1, ...draft }))),
-  });
-}));
+export const NotesHandlers = Notes.toLayer(
+	Effect.gen(function* () {
+		const stored = yield* Ref.make(
+			new Map([
+				[1, new Note({ body: "", id: 1, title: "One" })],
+				[2, new Note({ body: "", id: 2, title: "Two" })],
+			]),
+		);
+		const find = (id: number) =>
+			Effect.flatMap(Ref.get(stored), (all) => {
+				const note = all.get(id);
+				return note === undefined ? Get.reject.NoteMissing({ id }) : Effect.succeed(note);
+			});
+		const save = (note: Note) => Ref.update(stored, (all) => new Map([...all, [note.id, note]])).pipe(Effect.as(note));
+		return Notes.of({
+			"notes.$changes": () => Stream.never,
+			"notes.get": ({ id }) => find(id),
+			"notes.list": () => Effect.map(Ref.get(stored), (all) => [...all.values()]),
+			"notes.rename": ({ id, title }) =>
+				title.trim() === ""
+					? Rename.reject.Invalid({ field: "title", message: "Enter a title" })
+					: Effect.flatMap(find(id), (note) => save(new Note({ ...note, title }))),
+			"notes.create": (draft) =>
+				draft.title === ""
+					? Create.reject.Invalid({ field: "title", message: "Enter a title" })
+					: Effect.flatMap(Ref.get(stored), (all) => save(new Note({ id: all.size + 1, ...draft }))),
+		});
+	}),
+);
 ```
 
 Save this module as `handlers.ts`. An application can put repository and service calls in these handlers. The contract checks handler result and rejection types; it does not implement persistence, authorization or transactions. This in-memory server keeps the reserved change stream open without publishing hints. When a Platform host supplies that handler, build application handlers from `Notes.application` and keep `Notes` as the host and client group.
@@ -174,7 +183,7 @@ import { Notes } from "./notes.ts";
 import { NotesHandlers } from "./handlers.ts";
 
 export const NotesRoutes = RpcServer.layerHttp({ group: Notes, path: "/rpc", protocol: "http" }).pipe(
-  Layer.provide([NotesHandlers, RpcSerialization.layerJson]),
+	Layer.provide([NotesHandlers, RpcSerialization.layerJson]),
 );
 ```
 
@@ -189,16 +198,35 @@ import { bind } from "@shivaedev/contract/bind.ts";
 import { Notes } from "./notes.ts";
 
 export class NotesClient extends AtomRpc.Service<NotesClient>()("app/NotesClient", {
-  group: Notes,
-  protocol: RpcClient.layerProtocolHttp({ url: "http://127.0.0.1:3000/rpc" }).pipe(
-    Layer.provide([FetchHttpClient.layer, RpcSerialization.layerJson]),
-  ),
+	group: Notes,
+	protocol: RpcClient.layerProtocolHttp({ url: "http://127.0.0.1:3000/rpc" }).pipe(
+		Layer.provide([FetchHttpClient.layer, RpcSerialization.layerJson]),
+	),
 }) {}
 export const api = bind(Notes, NotesClient);
 ```
 
 Save the client module as `client.ts`. The [native RPC guide](https://github.com/ShivaeDev/platform/blob/main/docs/framework/native-rpc.md) covers hosting; the [reference composition](https://github.com/ShivaeDev/platform/blob/main/docs/framework/composed-example.md) composes handlers, request identity, SQL and a rendered client.
 
+### Build an HTTP client in one call
+
+Instead of declaring the `AtomRpc.Service` yourself, use `makeClient` once per session to build the HTTP client and bind the contract to it:
+
+```ts
+import { HttpClient, HttpClientRequest } from "effect/http";
+import { makeClient } from "@shivaedev/contract/bind.ts";
+import { Notes } from "./notes.ts";
+
+const { api, runtime } = makeClient(Notes, {
+	url: "/rpc",
+	transformClient: (client) => HttpClient.mapRequest(client, HttpClientRequest.setHeader("authorization", "Bearer session-token")),
+});
+const note = api.get.query({ id: 1 });
+const rename = runtime.fn(api.rename.run);
+```
+
+The request transform is optional and its native HTTP client type is inferred. Tests can set cookie and Origin headers through the same option. The default transport uses Fetch and NDJSON; `httpClient` and `serialization` accept native Layers for another HTTP client or codec. `group` can supply a larger native RPC group containing the contract, such as an admin registry. The result is a native client Layer that a host can pass to `ManagedRuntime.make`. It also exposes the native `Client` service and a scoped `client` Effect for callers outside React. Session-scoped contracts require `registry` in the options, just as `bind` does.
+
 ### 3. Every day: read and change
 
 ```ts
@@ -208,8 +236,6 @@ const readOnce = api.get.run({ id: 1 });
 const rename = api.rename.run({ id: 1, title: "Uno" });
 ```
 
-`queryCoalesceWindow(query)` from `@shivaedev/contract/queryCoalesceWindow.ts` returns a writable native atom for that bound query's live changed-hint window. Set it through the query's registry to a Duration, or `undefined` to use the live connection's default. Changing it does not refetch or reconnect; the next window uses the new value. React consumers can set it with `useQuery(query, { coalesceWindow: "2 seconds" })`.
-
 `one` and `list` are native query atoms. `readOnce` and `rename` are Effects for individual calls. A query's Effect requires `NotesClient`; a command's Effect also requires native `Reactivity`. Commands expose `run`, and have no `query` member.
 
 Mount the atoms and run commands through the service's atom runtime in the same registry:
@@ -225,9 +251,7 @@ const list = api.list.query();
 const releaseOne = registry.mount(one);
 const releaseList = registry.mount(list);
 
-const renamed = await Effect.runPromise(
-  AtomRegistry.getResult(registry, NotesClient.runtime.atom(api.rename.run({ id: 1, title: "Uno" }))),
-);
+const renamed = await Effect.runPromise(AtomRegistry.getResult(registry, NotesClient.runtime.atom(api.rename.run({ id: 1, title: "Uno" }))));
 
 releaseOne();
 releaseList();
@@ -238,54 +262,36 @@ The successful rename invalidates note 1 and the list. A rejected rename invalid
 
 The dependency rule is deliberately asymmetric:
 
-| Declared key | Query reads | Successful command invalidates |
-| --- | --- | --- |
-| `notes.item(1)` | `"notes:1"` | `"notes:1"` and `"notes"` |
-| `notes.list` | `"notes"` | `"notes"` |
+| Declared key    | Query reads | Successful command invalidates |
+| --------------- | ----------- | ------------------------------ |
+| `notes.item(1)` | `"notes:1"` | `"notes:1"` and `"notes"`      |
+| `notes.list`    | `"notes"`   | `"notes"`                      |
 
-`readKeys` and `invalidationKeys` produce these native keys and remove duplicates. An item change refreshes that item and its list, preserving other item queries. A list-only invalidation refreshes list queries and leaves item queries alone. These keys match native Reactivity's record-key hashing of `{ notes: [1] }`.
+`readKeys` and `invalidationKeys` from `@shivaedev/changes/keys.ts` produce these native keys and remove duplicates. An item change refreshes that item and its list, preserving other item queries. A list-only invalidation refreshes list queries and leaves item queries alone. These keys match native Reactivity's record-key hashing of `{ notes: [1] }`.
 
 Client invalidation follows RPC success. Database hosts from `@shivaedev/server` also publish declared command invalidations automatically after the handler succeeds, excluding keys already announced by repository commits, using `transact` from [`sql`](https://github.com/ShivaeDev/platform/tree/main/packages/sql); commit-bound changes belong to [`changes`](https://github.com/ShivaeDev/platform/tree/main/packages/changes).
 
 ### Session-owned keys
 
-Before migration, an owner field exists only to give client reads and invalidations a key. The server already chooses the account from `Identity`:
-
-```ts
-const preferences = collection("preferences", Schema.String);
-const Preferences = contract("preferences", {
-  queries: [query("self", {
-    payload: { ownerId: Schema.String },
-    reads: ({ ownerId }) => [preferences.item(ownerId)],
-    success: Schema.String,
-  })],
-  commands: [command("save", {
-    payload: { ownerId: Schema.String, title: Schema.String },
-    invalidates: ({ ownerId }) => [preferences.item(ownerId)],
-    success: Schema.String,
-  })],
-}).middleware(Authenticated);
-
-const api = bind(Preferences, Client);
-const self = api.self.query({ ownerId: session.userId });
-const save = api.save.run({ ownerId: session.userId, title: "My preferences" });
-```
-
-After migration, remove `ownerId` from both payload schemas and every call site. Add `keyScope: "session"` and keep a logical item key for the self-only record:
+A self-only feature, such as a user's preferences, reads and changes only the signed-in account's records. Declare its contract with `keyScope: "session"`. The server chooses the account from request-local identity, so payloads carry no owner field, and reads and invalidations name a logical item key for the record:
 
 ```ts
 const preferences = collection("preferences", Schema.String);
 const Preferences = contract("preferences", {
-  keyScope: "session",
-  queries: [query("self", {
-    reads: () => [preferences.item("self")],
-    success: Schema.String,
-  })],
-  commands: [command("save", {
-    payload: { title: Schema.String },
-    invalidates: () => [preferences.item("self")],
-    success: Schema.String,
-  })],
+	keyScope: "session",
+	queries: [
+		query("self", {
+			reads: () => [preferences.item("self")],
+			success: Schema.String,
+		}),
+	],
+	commands: [
+		command("save", {
+			payload: { title: Schema.String },
+			invalidates: () => [preferences.item("self")],
+			success: Schema.String,
+		}),
+	],
 }).middleware(Authenticated);
 
 const api = bind(Preferences, Client, { registry });
@@ -293,30 +299,14 @@ const self = api.self.query(undefined);
 const save = api.save.run({ title: "My preferences" });
 ```
 
-The examples use `Schema` and `Effect` from `effect`, `contract`, `query`, `command`, `collection` and `bind` from contract's defining modules, and `Authenticated` from `@shivaedev/identity/middleware.ts`. `Client` is the application's native AtomRpc service. In React, obtain `registry` from the second argument to `SessionBoundary.connect`:
-
-```tsx
-import { SessionBoundary } from "@shivaedev/react/client/sessionBoundary.ts";
-
-<SessionBoundary
-  session={session}
-  identify={(current) => current.generation}
-  connect={(current, registry) => bind(Preferences, makePreferencesClient(current.token), { registry })}
-  recheck={recheck}
-  signedOut={<p>Signed out</p>}
->
-  {(api) => <PreferencesScreen api={api} />}
-</SessionBoundary>
-```
-
-`makePreferencesClient(token)` creates the application's native AtomRpc service and configures its transport credentials. Existing one-argument `connect` callbacks continue to work. The boundary allocates the registry before calling `connect`; an unchanged generation keeps its binding and state. Account replacement, sign-out and same-account re-entry dispose the old registry, private query tracking, live registrations and pending refreshes. Choose a generation that changes whenever the auth owner starts a new session.
+The examples use `Schema` and `Effect` from `effect`, `contract`, `query`, `command` and `bind` from contract's defining modules, `collection` from `@shivaedev/changes/keys.ts`, and `Authenticated` from `@shivaedev/identity/middleware.ts`. `Client` is the application's native AtomRpc service, and `registry` is the atom registry that owns the session's queries. In React, `SessionBoundary` supplies that registry to `connect`, as [react's session-scoped bindings](https://github.com/ShivaeDev/platform/blob/main/packages/react/README.md#session-scoped-bindings) show.
 
-Handlers continue reading the account from request-local `Identity`, imported from `@shivaedev/identity/identity.ts`, before and after migration:
+Handlers read the account from request-local `Identity`, imported from `@shivaedev/identity/identity.ts`:
 
 ```ts
 Preferences.application.toLayer({
-  "preferences.self": () => Effect.flatMap(Identity, ({ id }) => store.read(id)),
-  "preferences.save": ({ title }) => Effect.flatMap(Identity, ({ id }) => store.save(id, title)),
+	"preferences.self": () => Effect.flatMap(Identity, ({ id }) => store.read(id)),
+	"preferences.save": ({ title }) => Effect.flatMap(Identity, ({ id }) => store.save(id, title)),
 });
 ```
 
@@ -340,9 +330,12 @@ import type { ResumeSource } from "@shivaedev/contract/resume.ts";
 import { onAppResume, onNetworkReturn } from "./native-lifecycle.ts";
 
 const resume: ResumeSource = (notify) => {
-  const stopApp = onAppResume(notify);
-  const stopNetwork = onNetworkReturn(notify);
-  return () => { stopApp(); stopNetwork(); };
+	const stopApp = onAppResume(notify);
+	const stopNetwork = onNetworkReturn(notify);
+	return () => {
+		stopApp();
+		stopNetwork();
+	};
 };
 const api = bind(Notes, NotesClient, { resume });
 ```
@@ -355,14 +348,14 @@ For a direct subscription, configure the server and `NotesClient` with `RpcSeria
 import { Effect, Stream } from "effect";
 import { NotesClient } from "./client.ts";
 
-const changes = Stream.unwrap(NotesClient.use((client) =>
-  Effect.succeed(client("notes.$changes", { queries: [{ query: "get", payload: { id: 1 } }] })),
-));
+const changes = Stream.unwrap(
+	NotesClient.use((client) => Effect.succeed(client("notes.$changes", { queries: [{ query: "get", payload: { id: 1 } }] }))),
+);
 ```
 
-The contract includes the reserved stream's payload, `LiveHint` elements and middleware failures in its native RPC type. The subscription uses the contract's middleware and needs no separate RPC group or cast. The caller owns stream consumption and interruption. References name declared queries and reuse their payload schemas; payloadless queries use `{ query: "list", payload: undefined }`. Subscription handlers resolve keys with `queryKeys(Notes.declaration.queries, queries)` from `serverMetadata.ts`, or the stream RPC's `ChangesReads` annotation, before calling `makeLiveServer.stream`. Session-scoped bindings track mounted queries per registry and drop their references on unmount or disposal. Ordinary bindings track query references when atoms are created.
+The contract includes the reserved stream's payload, `LiveHint` elements and middleware failures in its native RPC type. The subscription uses the contract's middleware and needs no separate RPC group or cast. The caller owns stream consumption and interruption. References name declared queries and reuse their payload schemas; payloadless queries use `{ query: "list", payload: undefined }`. Custom subscription handlers yield the Effect from the `ChangesQueries` annotation's `resolve(references)` method, call `querySubscription(requests, viewer)` and pass its authorized result to `makeLiveServer.subscribe(subscription, context)`. Hosted applications use `resolveChanges` from identity to supply that subscription. Session-scoped bindings track mounted queries per registry and drop their references on unmount or disposal. Ordinary bindings track query references when atoms are created.
 
-For a custom transport or explicit pause/status controls, the native live APIs remain available:
+For a custom transport or explicit pause and status controls, use the native live APIs.
 
 Declare subscriptions with `stream` in the same contract. Its `success` schema describes each element, and its `rejections` become the native stream error schema. `bind` exposes `run(payload)` as a native `Stream`, preserving declared rejections, middleware errors and RPC client errors. Completion and client interruption release the server subscription. The compiler rejects a unary client for a streaming operation.
 
@@ -395,18 +388,18 @@ import { LiveNotes } from "./live-notes.ts";
 import { notes } from "./notes.ts";
 
 class Client extends AtomRpc.Service<Client>()("app/LiveNotes", {
-  group: LiveNotes,
-  protocol: RpcClient.layerProtocolHttp({ url: "http://127.0.0.1:3000/rpc" }).pipe(
-    Layer.provide([FetchHttpClient.layer, RpcSerialization.layerNdjson]),
-  ),
+	group: LiveNotes,
+	protocol: RpcClient.layerProtocolHttp({ url: "http://127.0.0.1:3000/rpc" }).pipe(
+		Layer.provide([FetchHttpClient.layer, RpcSerialization.layerNdjson]),
+	),
 }) {}
 const api = bind(LiveNotes, Client);
 const registry = AtomRegistry.make();
 const updates = live(Client.runtime, {
-  stream: api.subscribe.run(undefined),
-  resyncKeys: [notes.item(1), notes.item(2), notes.list],
-  resume: resumeSignal({ window }),
-  retryDelay: "100 millis",
+	stream: api.subscribe.run(undefined),
+	resyncKeys: [notes.item(1), notes.item(2), notes.list],
+	resume: resumeSignal({ window }),
+	retryDelay: "100 millis",
 });
 const releaseQuery = registry.mount(api.get.query({ id: 1 }));
 const releaseConnection = registry.mount(updates.connection);
@@ -414,14 +407,16 @@ const releaseConnection = registry.mount(updates.connection);
 
 `LiveNotes` supplies both the declaration for binding and the native RPC group for transport. Stream read keys describe its dependencies; `run` does not mount query atoms or trigger automatic invalidation. Here the caller explicitly reconciles two items and their list. `bind` also accepts a larger native client group that preserves the contract RPC types. The [live updates guide](https://github.com/ShivaeDev/platform/blob/main/docs/framework/live-updates.md) shows server and client composition, and the [HTTP fixture](https://github.com/ShivaeDev/platform/tree/main/packages/contract/src/test-support/live) supplies a complete working server.
 
-| Observation | Invalidation |
-| --- | --- |
-| `Changed` with keys after the first hint | Affected items and their lists. |
-| `Resync` | The exact `resyncKeys` read scope. |
+| Observation                               | Invalidation                                           |
+| ----------------------------------------- | ------------------------------------------------------ |
+| `Changed` with keys after the first hint  | Affected items and their lists.                        |
+| `Resync`                                  | The exact `resyncKeys` read scope.                     |
 | First hint on a new or reconnected stream | The full explicit scope, even if the hint is targeted. |
 
 Changed hints share a fixed 20 ms window by default. Their keys merge, and each affected bound query refetches once per window. A bound query already fetching keeps its request and refetches once more after it settles if further hints arrive. Set `coalesceWindow` in `live()` to a native Duration, or set `SessionBoundary`'s `liveCoalesceWindow` for automatic session connections. Zero restores immediate per-hint invalidation, including interruption of in-flight reads. Full reconciliation on first hint, reconnect, resume and unpause stays immediate. Registry teardown cancels a pending window.
 
+`queryCoalesceWindow(query)` from `@shivaedev/contract/queryCoalesceWindow.ts` returns a writable native atom for that bound query's live changed-hint window. Set it through the query's registry to a Duration, or `undefined` to use the live connection's default. Changing it does not refetch or reconnect; the next window uses the new value. React consumers can set it with `useQuery(query, { coalesceWindow: "2 seconds" })`.
+
 `LiveHint` and `Key` are schemas. Decoding rejects unknown hint tags and item keys with an invalid ID type.
 
 ```ts
@@ -448,39 +443,33 @@ Call the release functions and dispose the registry when the application's root
 
 Import `makeLiveServer` from `@shivaedev/contract/makeLiveServer.ts` and create it once with the server's `Reactivity` service. After application authorization, return `hints.stream([orders.item(id)])` from the native streaming RPC handler. Each subscription starts with `Resync`; invalidating its read keys produces `Changed` with those declared keys. `hints.resync` sends `Resync` to every live stream owned by that helper, including streams for otherwise unrelated keys. Independent helpers keep their resync scopes separate even when they share Reactivity. The native stream owns registration and interruption. Keep this server helper separate from the browser's `live` coordinator.
 
-For viewer-scoped hints, call `authorizeReads` once in the application's native authorization middleware, after resolving the session:
+### Query policies, record keys and buckets
+
+A query declares its decoded input, result, `readPolicy` and `reads` together. `readPolicy(payload, viewer)` returns an Effect boolean. `viewer` is the session's `Option<{ id: string }>`; the browser does not send the identity. Policies may use browser-safe Effect service tags whose implementations the server supplies.
 
 ```ts
-import { authorizeReads } from "@shivaedev/contract/readPolicy.ts";
-
-const guard = Layer.succeed(Guard, (effect, request) =>
-  Effect.flatMap(resolveSession(request.headers), (session) =>
-    authorizeReads(effect, request, (key) => canRead(session, key), Effect.fail(new Denied())).pipe(
-      Effect.provideService(Session, session),
-    ),
-  ),
-);
+import { Effect, Option, Schema } from "effect";
+import { collection } from "@shivaedev/changes/keys.ts";
+import { query } from "@shivaedev/contract/operation.ts";
+
+const notes = collection("notes", Schema.Number, { userId: Schema.String });
+const Mine = query("mine", {
+	payload: { title: Schema.String },
+	success: Schema.Array(Schema.String),
+	readPolicy: (_input, viewer) => Effect.succeed(Option.isSome(viewer)),
+	reads: (_input, viewer) => (Option.isSome(viewer) ? [notes.bucket.userId(viewer.value.id)] : []),
+});
 ```
 
-The application supplies `resolveSession`, `canRead` and its middleware's `Denied` failure. Apply this middleware to the contract, including its reserved change stream. The policy returns `Effect<boolean, PolicyError, PolicyServices>` for a key. `authorizeReads` checks every declared query read key before running its handler and supplies the same policy to `makeLiveServer` streams, with the request's Effect context. Queries need no additional authorization declaration. A `false` returns the supplied denial; a failed policy returns its original typed error. Declare policy errors alongside the denial in the native middleware's error schema so they reach the client, for example `error: Schema.Union([Denied, GitHubUnavailable])`.
-
-Each changed hint checks its keys against that viewer's policy before delivery and omits denied keys. An empty hint is suppressed. Item and list keys are checked independently: allow a list key when the viewer may read that list, even when a changed item is private to another viewer. The list query still selects its visible rows. Without a supplied `ReadPolicy`, streams keep the default of allowing their subscribed keys; applications own the policy.
+A record key, `notes.item(id)`, names one record. A bucket, `notes.bucket.userId(id)`, names every row with that field value. Declare bucket fields on the collection model with their schemas. A list may add title, state or other filters to its input and handler, but those filters never narrow its bucket. It reruns whenever any row in that bucket changes, including a row excluded by the filter. Writers explicitly announce the record and affected buckets with the same constructors from `@shivaedev/changes/keys.ts`.
 
-A failed hint check omits that key without ending the stream. The subscription rechecks failed keys after one second and repeats while checks fail. Once allowed, the key reaches the existing consumer even without another change or a reconnect. A `false` does not schedule a recheck. Interruption of the subscription stops its pending rechecks.
+The same query policy guards running the query and subscribing to it. A subscription names query references, never arbitrary record or bucket keys. The entire subscription is refused with `QueryReadDenied` if any referenced query is denied. Without `readPolicy`, a query has no authorized live subscription: `MissingReadPolicy` tells its author to declare one. Bound query atoms also refuse a missing policy before their first read. Ordinary one-off `run` calls remain available. Reads outside a declared query acquire no automatic subscription.
 
-Successful boolean results are memoised per subscription stream and key for one second by default, including `false`; failures are never memoised. Queries always run their policy afresh. The memo holds at most the subscription's key count. It can delay filtering a revoked key from hints by at most that window; hints contain keys, and the subsequent query still checks current access before returning data. Set `ReadPolicyMemoWindow` around the request effect to shorten the window or use `0` to turn memoisation off:
-
-```ts
-import { ReadPolicyMemoWindow } from "@shivaedev/contract/readPolicy.ts";
-
-authorizeReads(effect, request, canRead, Effect.fail(new Denied())).pipe(
-  Effect.provideService(ReadPolicyMemoWindow, "100 millis"),
-);
-```
+The session middleware supplies the viewer and runs `authorizeReads(effect, request, viewer)`. Custom middleware calls that function after resolving its session and declares `MissingReadPolicy` and `QueryReadDenied` in its error schema. Before delivering changed keys, the stream rechecks the owning query's policy without memoization. A client refresh runs the same authorized query that produced its first value; hints carry no row values.
 
 ### Live hints in stories
 
-Use `watchHints` and `heard` from `@shivaedev/contract/testing.ts` in an application's story kit. Pass each viewer's authenticated live stream to `watchHints`; it starts a scoped subscription and waits for its first hint before returning the viewer handle. The contract's viewer story kit exposes these as `listen(viewer, queries)` and `heard(viewer, keys)`.
+Use `watchHints` and `heard` from `@shivaedev/contract/testing.ts` in an application's story kit. Pass each viewer's authenticated live stream to `watchHints`; it starts a scoped subscription and waits for its first hint before returning the viewer handle.
 
 ```ts
 const alice = yield* watchHints(aliceChanges);
@@ -496,30 +485,31 @@ expect(yield* heard(bob, [notes.item(1)], { within: "50 millis" })).toBe(false);
 
 Import the module that defines the name; the package has no root entry.
 
-| Module | Functions and schemas |
-| --- | --- |
-| `operation.ts` | `query(name, { payload?, success?, rejections?, reads })`; `command(name, { payload?, success?, rejections?, invalidates })`; `stream(name, { payload?, success, rejections?, reads })`. |
-| `contract.ts` | `contract(name, { queries?, commands?, streams?, keyScope? })`, returning a native RPC group with `declaration: { name, queries, commands, streams, keyScope }`. |
-| `rejection.ts` | `fieldRejection(struct, fields?)`; lower-level `rejectionSet(specs)`, which constructs the rejection classes, union schema and failure helpers used by operations. |
-| `keys.ts` | `collection(name, idSchema)`; `Key` schema; `readKeys(keys, context?)` and `invalidationKeys(keys, context?)`. |
-| `bind.ts` | `bind(contract, atomRpcService, { registry }?)`, requiring the registry for session-scoped contracts and exposing `{ query, run }` for queries, `{ run }` Effects for commands and `{ run }` native Streams for streams. |
-| `live.ts` | `LiveHint` schema; `live(runtime, { stream, resyncKeys, coalesceWindow?, keyContext?, resume?, retryDelay? })`, exposing `connection`, `coalesceWindow`, `paused` and `status`. |
-| `makeLiveServer.ts` | `makeLiveServer`, an Effect requiring `Reactivity` that creates scoped server hint streams and a `resync` Effect. |
-| `readPolicy.ts` | `authorizeReads(effect, request, policy, denied)`; `ReadPolicy`, the request-local fallible key policy used by server hint streams; `ReadPolicyMemoWindow`, a `Context.Reference<Duration.Input>` controlling each stream's memo duration. |
-| `serverMetadata.ts` | `KeyScope`, `QueryReads`, `CommandInvalidation`, `ChangesReads`, `queryKeys(queries, references)` and `changesRpc(name, queries)` for server adapters. |
-| `resume.ts` | `resumeSignal({ window?, native? })`, returning a native numeric signal atom. |
-| `testing.ts` | `watchHints(stream)` starts a scoped viewer subscription; `heard(viewer, keys, { within? }?)` waits for matching changed keys. |
+| Module                   | Functions and schemas                                                                                                                                                                                                                                                                                                                                                  |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `operation.ts`           | `query(name, { payload?, success?, rejections?, readPolicy?, reads })`; `command(name, { payload?, success?, rejections?, invalidates })`; `stream(name, { payload?, success, rejections?, reads })`.                                                                                                                                                                  |
+| `contract.ts`            | `contract(name, { queries?, commands?, streams?, keyScope? })`, returning a native RPC group with `declaration: { name, queries, commands, streams, keyScope }`.                                                                                                                                                                                                       |
+| `rejection.ts`           | `fieldRejection(struct, fields?)`; lower-level `rejectionSet(specs)`, which constructs the rejection classes, union schema and failure helpers used by operations.                                                                                                                                                                                                     |
+| `bind.ts`                | `bind(contract, atomRpcService, { registry }?)`, requiring the registry for session-scoped contracts and exposing `{ query, run }` for queries, `{ run }` Effects for commands and `{ run }` native Streams for streams; `makeClient(contract, { url, transformClient?, httpClient?, serialization?, group?, registry? })`, which builds the HTTP client and binds it. |
+| `queryCoalesceWindow.ts` | `queryCoalesceWindow(query)`, a writable atom for a bound query's live changed-hint window.                                                                                                                                                                                                                                                                            |
+| `live.ts`                | `LiveHint` schema; `live(runtime, { stream, resyncKeys, coalesceWindow?, keyContext?, resume?, retryDelay? })`, exposing `connection`, `coalesceWindow`, `paused` and `status`.                                                                                                                                                                                        |
+| `querySubscription.ts`   | `querySubscription(requests, viewer)` checks each referenced query and captures its scopes and ongoing authorization.                                                                                                                                                                                                                                                  |
+| `makeLiveServer.ts`      | `makeLiveServer`, an Effect requiring `Reactivity` that creates scoped server hint streams and a `resync` Effect.                                                                                                                                                                                                                                                      |
+| `readPolicy.ts`          | `QueryReadPolicy`, `Viewer`, `authorizeReads(effect, request, viewer)`, `CurrentViewer`.                                                                                                                                                                                                                                                                               |
+| `readPolicyErrors.ts`    | `MissingReadPolicy` and `QueryReadDenied`.                                                                                                                                                                                                                                                                                                                             |
+| `serverMetadata.ts`      | `KeyScope`, `QueryDefinition.definition`, `CommandInvalidation.invalidates`, `ChangesQueries.resolve(references)`, the Effect `queryKeys(queries, references)` and `changesRpc(name, queries)` for server adapters.                                                                                                                                                    |
+| `resume.ts`              | `resumeSignal({ window?, native? })`, returning a native numeric signal atom.                                                                                                                                                                                                                                                                                          |
+| `testing.ts`             | `watchHints(stream)` starts a scoped viewer subscription; `heard(viewer, keys, { within? }?)` waits for matching changed keys.                                                                                                                                                                                                                                         |
 
 A query atom takes native query options as its optional second argument, for example `api.get.query({ id: 1 }, { timeToLive: "1 minute" })`. A native resume source receives a callback and returns a cleanup function.
 
 ### Install, setup and limits
 
 ```sh
-pnpm add @shivaedev/contract effect@4.0.5
+pnpm add @shivaedev/contract effect
 ```
 
 `effect` is a peer, and the package needs Node.js 24 or newer. Choose the native server host separately; this package supplies no server process or HTTP transport implementation.
-
 - Put schema declarations where server and browser can share them. Put service, authorization and transaction implementations on the server. React rendering and editable forms belong to `react` and `form`.
 - Run command Effects with the Reactivity instance that owns the queries to refresh, as in the registry example.
 - Choose a common read key for every query in a full reconciliation scope. A list key does not implicitly cover item queries.