@shivaedev/contract 0.0.0 → 0.16.0

package/dist/serverMetadata.js

@@ -0,0 +1,27 @@
+import { Context, Schema } from "effect";
+import { Rpc } from "effect/rpc";
+import { LiveHint } from "#live.ts";
+export class QueryReads extends Context.Service()("@shivaedev/contract/QueryReads") {
+}
+export class CommandInvalidation extends Context.Service()("@shivaedev/contract/CommandInvalidation") {
+}
+export class KeyScope extends Context.Service()("@shivaedev/contract/KeyScope") {
+}
+export class ChangesReads extends Context.Service()("@shivaedev/contract/ChangesReads") {
+}
+export function queryKeys(queries, requested) {
+    return requested.flatMap((reference) => {
+        const declared = queries.find((candidate) => candidate.name === reference.query);
+        if (declared === undefined) {
+            throw new Error(`Unknown query: ${reference.query}`);
+        }
+        return declared.reads(reference.payload);
+    });
+}
+function referenceSchemas(queries) {
+    return Schema.Array(Schema.Union(queries.map((query) => Schema.Struct({ payload: query.payload, query: Schema.Literal(query.name) }))));
+}
+export function changesRpc(name, queries) {
+    return Rpc.make(`${name}.$changes`, { payload: { queries: referenceSchemas(queries) }, stream: true, success: LiveHint }).annotate(ChangesReads, (requested) => queryKeys(queries, requested));
+}
+//# sourceMappingURL=serverMetadata.js.map

package/dist/serverMetadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serverMetadata.js","sourceRoot":"","sources":["../src/serverMetadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AAEjC,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAGpC,MAAM,OAAO,UAAW,SAAQ,OAAO,CAAC,OAAO,EAAmC,CAAC,gCAAgC,CAAC;CAAG;AAEvH,MAAM,OAAO,mBAAoB,SAAQ,OAAO,CAAC,OAAO,EAAoD,CAC3G,yCAAyC,CACzC;CAAG;AAEJ,MAAM,OAAO,QAAS,SAAQ,OAAO,CAAC,OAAO,EAAuB,CAAC,8BAA8B,CAAC;CAAG;AAWvG,MAAM,OAAO,YAAa,SAAQ,OAAO,CAAC,OAAO,EAA2E,CAC3H,kCAAkC,CAClC;CAAG;AAEJ,MAAM,UAAU,SAAS,CAAC,OAA8B,EAAE,SAAoC;IAC7F,OAAO,SAAS,CAAC,OAAO,CAAC,CAAC,SAAS,EAAE,EAAE;QACtC,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,KAAK,SAAS,CAAC,KAAK,CAAC,CAAC;QACjF,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CAAC,kBAAkB,SAAS,CAAC,KAAK,EAAE,CAAC,CAAC;QACtD,CAAC;QACD,OAAO,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IAC1C,CAAC,CAAC,CAAC;AACJ,CAAC;AAKD,SAAS,gBAAgB,CAAC,OAA8B;IACvD,OAAO,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AACzI,CAAC;AAED,MAAM,UAAU,UAAU,CAA2E,IAAW,EAAE,OAAiB;IAClI,OAAO,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,WAAW,EAAE,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,gBAAgB,CAAC,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,CACjI,YAAY,EACZ,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE,SAAS,CAAC,CAC5C,CAAC;AACH,CAAC"}

package/package.json

@@ -1,10 +1,79 @@
 {
   "name": "@shivaedev/contract",
-  "version": "0.0.0",
-  "description": "Placeholder for the ShivaeDev contract package.",
-  "license": "MIT",
+  "version": "0.16.0",
+  "description": "Typed query and command contracts over native Effect RPC and reactivity",
+  "keywords": [
+    "effect"
+  ],
+  "homepage": "https://github.com/ShivaeDev/platform/tree/main/packages/contract#readme",
+  "bugs": {
+    "url": "https://github.com/ShivaeDev/platform/issues"
+  },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ShivaeDev/platform.git"
+    "url": "git+https://github.com/ShivaeDev/platform.git",
+    "directory": "packages/contract"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "imports": {
+    "#test/*": "./src/test-support/*",
+    "#*.ts": {
+      "source": "./src/*.ts",
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  },
+  "exports": {
+    "./*.ts": {
+      "source": "./src/*.ts",
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    },
+    "./internal/*": null,
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.spec.ts",
+    "!src/**/test-support",
+    "CHANGELOG.md",
+    "README.md"
+  ],
+  "dependencies": {
+    "@shivaedev/types": "0.3.0"
+  },
+  "devDependencies": {
+    "@effect/platform-node": "4.0.5",
+    "@effect/vitest": "4.0.5",
+    "@shivaedev/quality": "0.41.1",
+    "@shivaedev/test": "0.9.0",
+    "@shivaedev/test-sql": "0.9.3",
+    "@shivaedev/test-story": "0.20.1",
+    "@types/node": "24.19.2",
+    "effect": "4.0.5",
+    "esbuild": "0.28.2",
+    "happy-dom": "21.0.3",
+    "typescript": "7.0.2",
+    "vitest": "5.0.5"
+  },
+  "peerDependencies": {
+    "effect": "4.0.5"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "node --eval \"import('node:fs').then(({ rmSync }) => rmSync('dist', { force: true, recursive: true }))\" && tsc --project tsconfig.build.json",
+    "ready": "pnpm typecheck && pnpm test && pnpm build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   }
 }

package/src/automaticLive.ts

@@ -0,0 +1,93 @@
+import { type Duration, Effect, Stream, SubscriptionRef } from "effect";
+import * as Atom from "effect/reactivity/Atom";
+import * as AtomRegistry from "effect/reactivity/AtomRegistry";
+import type * as AtomRpc from "effect/reactivity/AtomRpc";
+import type { BindingOwner } from "#internal/bindingOwner.ts";
+import { type Key, readKeys } from "#keys.ts";
+import { type LiveStatus, live } from "#live.ts";
+import { type ResumeSource, type ResumeWindow, resumeSignal } from "#resume.ts";
+import type { changesRpc, QueryReference } from "#serverMetadata.ts";
+
+declare const window: ResumeWindow | undefined;
+
+export const LiveConnection = Symbol.for("@shivaedev/contract/LiveConnection");
+export interface LiveBound {
+	readonly [LiveConnection]: {
+		readonly coalesceWindow: Atom.Writable<Duration.Input>;
+		readonly connection: Atom.Atom<unknown>;
+		readonly status: Atom.Atom<LiveStatus<unknown>>;
+	};
+}
+
+export type ChangesClient = AtomRpc.AtomRpcClient<unknown, string, ReturnType<typeof changesRpc>>;
+
+interface Tracked {
+	readonly keys: readonly Key[];
+	readonly reference: QueryReference;
+}
+
+export function automaticLive(service: ChangesClient, name: string, owner?: BindingOwner, resume?: ResumeSource) {
+	const eager = owner === undefined ? Effect.runSync(SubscriptionRef.make<ReadonlyMap<object, Tracked>>(new Map())) : undefined;
+	const known = new Set<string>();
+	const tracked = Atom.keepAlive(Atom.make(() => eager ?? Effect.runSync(SubscriptionRef.make<ReadonlyMap<object, Tracked>>(new Map()))));
+	function track(registry: AtomRegistry.AtomRegistry | undefined, reference: QueryReference, keys: readonly Key[]) {
+		const fresh =
+			eager === undefined
+				? keys
+				: keys.filter((key) => {
+						const id = readKeys([key])[0] ?? "";
+						if (known.has(id)) {
+							return false;
+						}
+						known.add(id);
+						return true;
+					});
+		if (fresh.length === 0) {
+			return () => undefined;
+		}
+		const token = {};
+		const state = eager ?? registry?.get(tracked);
+		if (state === undefined) {
+			throw new Error("Session query tracking requires its owning registry");
+		}
+		Effect.runSync(SubscriptionRef.update(state, (current) => new Map([...current, [token, { keys: fresh, reference }]])));
+		if (eager !== undefined) {
+			return () => undefined;
+		}
+		return () =>
+			Effect.runSync(
+				SubscriptionRef.update(state, (current) => {
+					const next = new Map(current);
+					next.delete(token);
+					return next;
+				}),
+			);
+	}
+	function subscribe(current: ReadonlyMap<object, Tracked>) {
+		if (current.size === 0) {
+			return Stream.never;
+		}
+		const queries = [...current.values()].map(({ reference }) => reference);
+		return Stream.unwrap(service.use((client) => Effect.succeed(client(`${name}.$changes`, { queries }))));
+	}
+	const signal = resumeSignal({ ...(typeof window === "undefined" ? {} : { window }), ...(resume === undefined ? {} : { native: resume }) });
+	const subscription = live(service.runtime, {
+		keyContext: owner?.context,
+		resume: signal,
+		resyncKeys: (registry) => [...Effect.runSync(SubscriptionRef.get(registry.get(tracked))).values()].flatMap(({ keys }) => keys),
+		stream: Stream.unwrap(
+			Effect.map(AtomRegistry.AtomRegistry, (registry) =>
+				Stream.zipLatest(SubscriptionRef.changes(registry.get(tracked)), AtomRegistry.toStream(registry, signal)).pipe(
+					Stream.switchMap(([current]) => subscribe(current)),
+				),
+			),
+		),
+	});
+	const connection = Atom.make((get) => {
+		if (owner !== undefined && owner.registry !== get.registry) {
+			throw new Error("A session-scoped live connection belongs to its binding registry");
+		}
+		return get(subscription.connection);
+	}).pipe(Atom.setIdleTTL(0));
+	return { subscription: { ...subscription, connection }, track };
+}

package/src/bind.ts

@@ -0,0 +1,103 @@
+import type { Duration, Effect, Stream } from "effect";
+import type { Headers } from "effect/http";
+import type * as AsyncResult from "effect/reactivity/AsyncResult";
+import type * as Atom from "effect/reactivity/Atom";
+import type * as AtomRegistry from "effect/reactivity/AtomRegistry";
+import type * as AtomRpc from "effect/reactivity/AtomRpc";
+import type * as Reactivity from "effect/reactivity/Reactivity";
+import type { Rpc } from "effect/rpc";
+import type { RpcClientError } from "effect/rpc/RpcClientError";
+import { automaticLive, type LiveBound, LiveConnection } from "#automaticLive.ts";
+import type { Contract, Declared, Tag } from "#contract.ts";
+import { bindingOwner } from "#internal/bindingOwner.ts";
+import { boundCommand, boundQuery, boundStream } from "#internal/clientOperations.ts";
+import type { CommandShape, QueryShape, StreamShape } from "#operation.ts";
+import type { ResumeSource } from "#resume.ts";
+
+export type Failure<R extends Rpc.Any> =
+	R extends Rpc.Rpc<infer _Tag, infer _Payload, infer _Success, infer _Error, infer TMiddleware, infer _Requires>
+		? Rpc.ErrorExit<R> | TMiddleware["error"]["Type"] | RpcClientError
+		: never;
+
+export type RunFailure<R extends Rpc.Any> =
+	R extends Rpc.Rpc<infer _Tag, infer _Payload, infer _Success, infer _Error, infer TMiddleware, infer _Requires>
+		? Failure<R> | TMiddleware["~ClientError"]
+		: never;
+
+export interface QueryOptions {
+	readonly headers?: Headers.Input;
+	readonly serializationKey?: string;
+	readonly timeToLive?: Duration.Input;
+}
+
+export interface BoundQuery<R extends Rpc.Any, TSelf> {
+	readonly query: (payload: Rpc.Payload<R>, options?: QueryOptions) => Atom.Atom<AsyncResult.AsyncResult<Rpc.Success<R>, Failure<R>>>;
+	readonly run: (payload: Rpc.Payload<R>) => Effect.Effect<Rpc.Success<R>, RunFailure<R>, TSelf>;
+}
+
+export interface BoundCommand<R extends Rpc.Any, TSelf> {
+	readonly run: (payload: Rpc.Payload<R>) => Effect.Effect<Rpc.Success<R>, RunFailure<R>, TSelf | Reactivity.Reactivity>;
+}
+
+export interface BoundStream<R extends Rpc.Any, TSelf> {
+	readonly run: (payload: Rpc.Payload<R>) => Stream.Stream<Rpc.SuccessChunk<R>, RunFailure<R>, TSelf | Rpc.ServicesClient<R>>;
+}
+
+export type Bound<
+	TName extends string,
+	TQueries extends readonly QueryShape[],
+	TCommands extends readonly CommandShape[],
+	TRpcs extends Rpc.Any,
+	TSelf,
+	TStreams extends readonly StreamShape[] = readonly [],
+> = {
+	readonly [TQuery in TQueries[number] as TQuery["name"]]: BoundQuery<Rpc.ExtractTag<TRpcs, Tag<TName, TQuery["name"]>>, TSelf>;
+} & {
+	readonly [TCommand in TCommands[number] as TCommand["name"]]: BoundCommand<Rpc.ExtractTag<TRpcs, Tag<TName, TCommand["name"]>>, TSelf>;
+} & {
+	readonly [TStream in TStreams[number] as TStream["name"]]: BoundStream<Rpc.ExtractTag<TRpcs, Tag<TName, TStream["name"]>>, TSelf>;
+};
+
+type MatchingClient<TRpcs extends Rpc.Any, TClientRpcs extends Rpc.Any> = [TRpcs] extends [Extract<TClientRpcs, { readonly _tag: TRpcs["_tag"] }>]
+	? [Extract<TClientRpcs, { readonly _tag: TRpcs["_tag"] }>] extends [TRpcs]
+		? unknown
+		: "Client must preserve the contract RPC types"
+	: "Client must implement the contract RPCs";
+
+interface BindOptions {
+	readonly registry?: AtomRegistry.AtomRegistry;
+	readonly resume?: ResumeSource;
+}
+
+export function bind<
+	TName extends string,
+	TQueries extends readonly QueryShape[],
+	TCommands extends readonly CommandShape[],
+	TRpcs extends Rpc.Any,
+	TSelf,
+	TId extends string,
+	TClientRpcs extends Rpc.Any,
+	TStreams extends readonly StreamShape[],
+	TScope extends "session" | undefined,
+>(
+	contract: Contract<TName, TQueries, TCommands, TRpcs, TStreams, TScope>,
+	service: AtomRpc.AtomRpcClient<TSelf, TId, TClientRpcs> & MatchingClient<NoInfer<TRpcs>, TClientRpcs>,
+	...options: "session" extends TScope ? [options: BindOptions & { readonly registry: AtomRegistry.AtomRegistry }] : [options?: BindOptions]
+): Bound<TName, TQueries, TCommands, TRpcs, TSelf, TStreams> & LiveBound;
+export function bind(
+	contract: { readonly declaration: Declared<string, readonly QueryShape[], readonly CommandShape[], readonly StreamShape[], "session" | undefined> },
+	service: AtomRpc.AtomRpcClient<unknown, string, Rpc.Any>,
+	options?: BindOptions,
+): unknown {
+	const { name, queries, commands, streams, keyScope } = contract.declaration;
+	const owner = bindingOwner(keyScope, options?.registry);
+	const automatic = automaticLive(service, name, owner, options?.resume);
+	return Object.assign(
+		Object.fromEntries([
+			...queries.map((query) => [query.name, boundQuery(service, `${name}.${query.name}`, query, automatic.track, owner)] as const),
+			...commands.map((command) => [command.name, boundCommand(service, `${name}.${command.name}`, command, owner)] as const),
+			...streams.map((stream) => [stream.name, boundStream(service, `${name}.${stream.name}`)] as const),
+		]),
+		{ [LiveConnection]: automatic.subscription },
+	);
+}

package/src/contract.ts

@@ -0,0 +1,140 @@
+import { Context, type Schema } from "effect";
+import { Rpc, RpcGroup, type RpcMiddleware, type RpcSchema } from "effect/rpc";
+import type { CommandShape, OperationShape, QueryShape, StreamShape } from "#operation.ts";
+import { CommandInvalidation, changesRpc, KeyScope, QueryReads } from "#serverMetadata.ts";
+
+export type Tag<TContract extends string, TName extends string> = `${TContract}.${TName}`;
+
+export type OperationRpc<TContract extends string, TOperation> = TOperation extends OperationShape
+	? TOperation extends StreamShape
+		? Rpc.Rpc<Tag<TContract, TOperation["name"]>, TOperation["payload"], RpcSchema.Stream<TOperation["success"], TOperation["error"]>, Schema.Never>
+		: Rpc.Rpc<Tag<TContract, TOperation["name"]>, TOperation["payload"], TOperation["success"], TOperation["error"]>
+	: never;
+
+export interface Declared<
+	TName extends string,
+	TQueries extends readonly QueryShape[],
+	TCommands extends readonly CommandShape[],
+	TStreams extends readonly StreamShape[] = readonly [],
+	TScope extends "session" | undefined = undefined,
+> {
+	readonly commands: TCommands;
+	readonly keyScope: TScope;
+	readonly name: TName;
+	readonly queries: TQueries;
+	readonly streams: TStreams;
+}
+
+export interface Contract<
+	TName extends string,
+	TQueries extends readonly QueryShape[],
+	TCommands extends readonly CommandShape[],
+	TRpcs extends Rpc.Any = OperationRpc<TName, TQueries[number] | TCommands[number]> | ReturnType<typeof changesRpc<TName, TQueries>>,
+	TStreams extends readonly StreamShape[] = readonly [],
+	TScope extends "session" | undefined = undefined,
+> extends RpcGroup.RpcGroup<TRpcs> {
+	readonly application: RpcGroup.RpcGroup<Exclude<TRpcs, { readonly _tag: `${TName}.$changes` }>>;
+	readonly declaration: Declared<TName, TQueries, TCommands, TStreams, TScope>;
+	middleware: <TM extends RpcMiddleware.AnyService>(
+		middleware: TM,
+	) => Contract<TName, TQueries, TCommands, Rpc.AddMiddleware<TRpcs, TM>, TStreams, TScope>;
+}
+
+type Duplicated<TOperations extends readonly OperationShape[], TSeen extends string = never> = TOperations extends readonly [
+	infer THead extends OperationShape,
+	...infer TTail extends readonly OperationShape[],
+]
+	? (THead["name"] extends TSeen ? THead["name"] : never) | Duplicated<TTail, TSeen | THead["name"]>
+	: never;
+
+type Unique<TOperations extends readonly OperationShape[]> = [Duplicated<TOperations>] extends [never]
+	? unknown
+	: `Operation names must be unique; duplicated: ${Duplicated<TOperations>}`;
+
+function assertUnique(operations: readonly OperationShape[]) {
+	const duplicated = operations.map(({ name }) => name).filter((name, index, names) => names.indexOf(name) !== index);
+	if (duplicated.length > 0) {
+		throw new Error(`Operation names must be unique; duplicated: ${[...new Set(duplicated)].join(", ")}`);
+	}
+}
+
+function annotations(operation: QueryShape | CommandShape | StreamShape, keyScope: "session" | undefined) {
+	const scope = keyScope === undefined ? Context.empty() : Context.make(KeyScope, keyScope);
+	if (operation.kind === "command") {
+		return Context.add(scope, CommandInvalidation, operation.invalidates);
+	}
+	return operation.kind === "query" ? Context.add(scope, QueryReads, operation.reads) : scope;
+}
+
+type AnyDeclared = Declared<string, readonly QueryShape[], readonly CommandShape[], readonly StreamShape[], "session" | undefined>;
+
+interface Group {
+	middleware: (middleware: RpcMiddleware.AnyService) => Group;
+}
+
+interface DeclaredGroup extends Group {
+	readonly application: unknown;
+	readonly declaration: AnyDeclared;
+}
+
+function withDeclaration(group: Group, application: Group, declaration: AnyDeclared): DeclaredGroup {
+	const nativeMiddleware = group.middleware.bind(group);
+	return Object.assign(group, {
+		application,
+		declaration,
+		middleware: (middleware: RpcMiddleware.AnyService) =>
+			withDeclaration(nativeMiddleware(middleware), application.middleware(middleware), declaration),
+	});
+}
+
+export function contract<
+	const TName extends string,
+	const TQueries extends readonly QueryShape[] = readonly [],
+	const TCommands extends readonly CommandShape[] = readonly [],
+	const TStreams extends readonly StreamShape[] = readonly [],
+	const TScope extends "session" | undefined = undefined,
+>(
+	name: TName,
+	operations: {
+		readonly keyScope?: TScope;
+		readonly queries?: TQueries & Unique<TQueries>;
+		readonly commands?: TCommands & Unique<[...TQueries, ...TCommands]>;
+		readonly streams?: TStreams & Unique<[...TQueries, ...TCommands, ...TStreams]>;
+	},
+): Contract<
+	TName,
+	TQueries,
+	TCommands,
+	OperationRpc<TName, TQueries[number] | TCommands[number] | TStreams[number]> | ReturnType<typeof changesRpc<TName, TQueries>>,
+	TStreams,
+	TScope
+>;
+export function contract(
+	name: string,
+	operations: {
+		readonly keyScope?: "session";
+		readonly queries?: readonly QueryShape[];
+		readonly commands?: readonly CommandShape[];
+		readonly streams?: readonly StreamShape[];
+	},
+): DeclaredGroup {
+	const { queries = [], commands = [], streams = [], keyScope } = operations;
+	assertUnique([...queries, ...commands, ...streams]);
+	const rpcs = [...queries, ...commands, ...streams].map((operation) =>
+		Rpc.make(`${name}.${operation.name}`, {
+			error: operation.error,
+			payload: operation.payload,
+			stream: operation.kind === "stream",
+			success: operation.success,
+		}).annotateMerge(annotations(operation, keyScope)),
+	);
+	const application = RpcGroup.make(...rpcs);
+	const changes = changesRpc(name, queries);
+	return withDeclaration(application.add(keyScope === undefined ? changes : changes.annotate(KeyScope, keyScope)), application, {
+		commands,
+		keyScope,
+		name,
+		queries,
+		streams,
+	});
+}

package/src/internal/bindingOwner.ts

@@ -0,0 +1,24 @@
+import type * as AtomRegistry from "effect/reactivity/AtomRegistry";
+import type { KeyContext } from "#keys.ts";
+
+export interface BindingOwner {
+	readonly context: KeyContext;
+	readonly registry: AtomRegistry.AtomRegistry;
+}
+
+const contexts = new WeakMap<AtomRegistry.AtomRegistry, KeyContext>();
+
+export function bindingOwner(scope: "session" | undefined, registry?: AtomRegistry.AtomRegistry): BindingOwner | undefined {
+	if (scope === undefined) {
+		return undefined;
+	}
+	if (registry === undefined) {
+		throw new Error("A session-scoped contract requires its owning registry");
+	}
+	let context = contexts.get(registry);
+	if (context === undefined) {
+		context = { scope: crypto.randomUUID() };
+		contexts.set(registry, context);
+	}
+	return { context, registry };
+}

package/src/internal/clientOperations.ts

@@ -0,0 +1,74 @@
+import { Effect, type Schema, Stream } from "effect";
+import * as AtomRegistry from "effect/reactivity/AtomRegistry";
+import type * as AtomRpc from "effect/reactivity/AtomRpc";
+import * as Reactivity from "effect/reactivity/Reactivity";
+import type { Rpc, RpcSchema } from "effect/rpc";
+import type { automaticLive } from "#automaticLive.ts";
+import type { QueryOptions } from "#bind.ts";
+import { invalidationKeys, readKeys } from "#keys.ts";
+import type { CommandShape, QueryShape } from "#operation.ts";
+import type { BindingOwner } from "./bindingOwner.ts";
+import { queryReactivity } from "./queryReactivity.ts";
+
+type ErasedClient = AtomRpc.AtomRpcClient<unknown, string, Rpc.Rpc<string, Schema.Top, Schema.Top, Schema.Top>>;
+
+type ErasedStreamingClient = AtomRpc.AtomRpcClient<
+	unknown,
+	string,
+	Rpc.Rpc<string, Schema.Top, RpcSchema.Stream<Schema.Top, Schema.Top>, Schema.Never>
+>;
+
+function run<A, E>(service: ErasedClient, effect: Effect.Effect<A, E, unknown>, owner?: BindingOwner) {
+	return owner === undefined ? effect : Effect.suspend(() => AtomRegistry.getResult(owner.registry, service.runtime.atom(effect)));
+}
+
+export function boundQuery(
+	service: ErasedClient,
+	tag: string,
+	query: QueryShape,
+	track: ReturnType<typeof automaticLive>["track"],
+	owner?: BindingOwner,
+) {
+	const reactive = queryReactivity(service.runtime);
+	return {
+		query: (payload: unknown, options: QueryOptions = {}) => {
+			const atom = service.query(tag, payload, options);
+			const keys = query.reads(payload);
+			const reference = { payload, query: query.name };
+			if (owner === undefined) {
+				track(undefined, reference, keys);
+			}
+			return reactive(
+				atom,
+				readKeys(keys, owner?.context),
+				(registry) => (owner === undefined ? () => undefined : track(registry, reference, keys)),
+				owner?.registry,
+			);
+		},
+		run: (payload: unknown) =>
+			run(
+				service,
+				service.use((client) => client(tag, payload)),
+				owner,
+			),
+	};
+}
+
+export function boundCommand(service: ErasedClient, tag: string, command: CommandShape, owner?: BindingOwner) {
+	return {
+		run: (payload: unknown) =>
+			run(
+				service,
+				service
+					.use((client) => client(tag, payload))
+					.pipe(Effect.tap((result) => Reactivity.invalidate(invalidationKeys(command.invalidates(payload, result), owner?.context)))),
+				owner,
+			),
+	};
+}
+
+export function boundStream(service: ErasedStreamingClient, tag: string) {
+	return {
+		run: (payload: unknown) => Stream.unwrap(service.use((client) => Effect.succeed(client(tag, payload)))),
+	};
+}

package/src/internal/liveInvalidation.ts

@@ -0,0 +1,21 @@
+import type { Duration } from "effect";
+import type * as Reactivity from "effect/reactivity/Reactivity";
+
+interface Batch {
+	readonly active: () => boolean;
+	readonly seen: Set<() => void>;
+	readonly window: Duration.Input | undefined;
+}
+export const liveBatches = new WeakMap<Reactivity.Reactivity, Batch>();
+export function liveKeys(keys: readonly string[]) {
+	return keys.map((key) => `@shivaedev/live:${key}`);
+}
+
+export function invalidateLive(reactivity: Reactivity.Reactivity, keys: readonly string[], active: () => boolean, window?: Duration.Input) {
+	liveBatches.set(reactivity, { active, seen: new Set(), window });
+	try {
+		reactivity.invalidateUnsafe(window === undefined ? keys : liveKeys(keys));
+	} finally {
+		liveBatches.delete(reactivity);
+	}
+}

package/src/internal/makeHintPolicy.ts

@@ -0,0 +1,40 @@
+import { Cache, Data, Effect, Exit, Queue } from "effect";
+import type { Key } from "#keys.ts";
+import { ReadPolicy, ReadPolicyMemoWindow } from "#readPolicy.ts";
+
+export const makeHintPolicy = Effect.fnUntraced(function* (capacity: number, retry: (keys: readonly Key[]) => Effect.Effect<void>) {
+	const policy = yield* ReadPolicy;
+	const window = yield* ReadPolicyMemoWindow;
+	const cache = yield* Cache.makeWith(policy, {
+		capacity: Math.max(1, capacity),
+		timeToLive: (exit) => (Exit.isSuccess(exit) ? window : 0),
+	});
+	const failed = new Map<string, Key>();
+	const wake = yield* Queue.unbounded<void>();
+	yield* Queue.take(wake).pipe(
+		Effect.andThen(Effect.sleep("1 second")),
+		Effect.andThen(
+			Effect.suspend(() => {
+				const keys = [...failed.values()];
+				failed.clear();
+				return retry(keys);
+			}),
+		),
+		Effect.forever,
+		Effect.forkScoped,
+	);
+	return (keys: readonly Key[]) =>
+		Effect.filter(keys, (key) =>
+			Cache.get(cache, new Data.Class<Key>(key)).pipe(
+				Effect.catch(() =>
+					Effect.gen(function* () {
+						if (failed.size === 0) {
+							yield* Queue.offer(wake, undefined);
+						}
+						failed.set(JSON.stringify(key), key);
+						return false;
+					}),
+				),
+			),
+		);
+});